midi-topaz 0.0.1

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011 Ari Russo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.rdoc

@@ -0,0 +1,96 @@
+= topaz
+
+{pic}[http://images.treetrouble.net/images/topaz.jpg]
+
+MIDI syncable tempo in Ruby
+
+== Installation
+
+  gem install midi-topaz
+  
+== Requirements
+
+* {gamelan}[http://github.com/jvoorhis/gamelan]
+* {midi-eye}[http://github.com/arirusso/midi-eye]
+* {midi-message}[http://github.com/arirusso/midi-message]
+* {unimidi}[http://github.com/arirusso/unimidi]
+
+these will install automatically with the gem
+
+== Usage
+
+  require "topaz"
+  
+For demonstration purposes, here's a mock sequencer class and object
+
+  class Sequencer
+    
+    def step
+      @i ||= 0
+      $stdout.puts "step #{@i+=1}"
+    end
+      
+  end
+  
+  seq = 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
+
+  @tempo = Topaz::Tempo.new(130) { seq.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    
+
+  @input = UniMIDI::Input.first.open # an midi input 
+  
+  @tempo = Topaz::Tempo.new(:midi => @input) { seq.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
+
+  @output = UniMIDI::Output.first.open # a midi output 
+  
+  @tempo = Topaz::Tempo.new(120, :midi => @output) { seq.step }
+  
+Input and multiple outputs can be used simultaneously
+
+  @tempo = Topaz::Tempo.new(:midi => [@input, @output1, @output2]) { seq.step }
+  
+Once the Tempo object is initialized, start the clock
+
+  @tempo.start
+  
+If you are syncing to external clock, nothing will happen until a "start" or "clock" message is received
+  
+==== Other things to note
+
+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, 16th notes will occur at 138 BPM   
+
+  @tempo = Topaz::Tempo.new(138, :interval => 16) { seq.step }
+  
+View the current tempo, which is calculated by Topaz if you're using an external MIDI source.
+(this feature is currently in-progress and may return some low values - 5/26/2011)
+
+  @tempo.tempo
+    => 132.422000
+      
+Run the generator in a background thread by passing :background => true to Tempo#start
+
+  @tempo.start(:background => true)
+  
+Pass in a block that will stop the clock when it evaluates to true
+
+  @tempo.stop_when { @i.eql?(20) }
+    
+== Documentation
+
+* {examples}[http://github.com/arirusso/topaz/tree/master/examples]
+* {rdoc}[http://rdoc.info/gems/midi-topaz] 
+
+== Author
+
+* {Ari Russo}[http://github.com/arirusso] <ari.russo at gmail.com>
+
+== License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011 Ari Russo

data/lib/topaz/external_midi_tempo.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+module Topaz
+  
+  # trigger an event based on received midi clock messages
+  class ExternalMIDITempo
+   
+    attr_accessor :action
+    attr_reader :clock
+  
+    def initialize(input, options = {})
+      @action = options[:action]
+      self.interval = options[:interval] || 4
+      @tempo_calculator = TempoCalculator.new
+      @clock = MIDIEye::Listener.new(input)
+      
+      initialize_clock 
+    end
+    
+    # this will return a calculated tempo
+    def tempo
+      @tempo_calculator.find_tempo
+    end
+    
+    def start(*a)
+      @action[:on_start].call unless @action[:on_start].nil?
+      @clock.start(*a)
+    end
+    
+    def stop(*a)
+      @action[:on_stop].call unless @action[:on_stop].nil?
+      @clock.start(*a)
+    end
+    
+    def join
+      @clock.join
+    end
+        
+    #
+    # change the clock interval
+    # defaults to click once every 24 ticks or one quarter note which is the MIDI standard.
+    # however, if you wish to fire the on_tick event twice as often 
+    # (or once per 12 clicks), pass 8 
+    #
+    #   1 = whole note
+    #   2 = half note
+    #   4 = quarter note
+    #   6 = dotted quarter
+    #   8 = eighth note
+    #  16 = sixteenth note
+    #  etc
+    #
+    def interval=(val)
+      per_qn = val / 4
+      @per_tick = 24 / per_qn
+    end
+    
+    private
+    
+    def initialize_clock
+      @counter = 0
+      @clock.listen_for(:name => "Clock") do |msg|
+        if !@action[:stop_when].nil? && @action[:stop_when].call
+          stop
+          return
+        end 
+        @action[:destinations].each do |output|
+          output.on_tick
+        end        
+        @tempo_calculator.timestamps << msg[:timestamp]
+        if @counter.eql?(@per_tick)
+          @action[:on_tick].call
+          @counter = 0 
+        else
+          @counter += 1
+        end
+      end
+    end
+    
+  end
+  
+end

data/lib/topaz/internal_tempo.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+module Topaz
+
+  class InternalTempo < Gamelan::Timer
+    
+    attr_accessor :action
+    
+    def initialize(tempo, options = {})
+      @action = options[:action]
+      self.interval = options[:interval] || 4 
+      @destinations = options[:destinations]
+      @last = 0
+      @last_sync = 0
+      super({:tempo => tempo})
+    end
+
+    # start the internal timer
+    # pass :background => true to keep the timer in a background thread
+    def start(options = {})
+      @action[:on_start].call unless @action[:on_start].nil?
+      run
+      join unless options[:background]
+    end
+    
+    # change the timer's click interval    
+    def interval=(val)
+      @interval = val / 4
+    end
+    
+    # stop the timer
+    def stop(*a)
+      @action[:on_stop].call unless @action[:on_stop].nil?
+      super
+    end
+    
+    protected
+    
+    # Run all ready tasks.
+    def dispatch
+      # stuff to do on every tick      
+      unless @last_sync.eql?((@phase * 24).to_i)
+        # look for stop
+        if !@action[:stop_when].nil? && @action[:stop_when].call
+          stop
+          return
+        end 
+        @action[:destinations].each { |dest| dest.on_tick }        
+        @last_sync = (@phase * 24).to_i
+      end
+      # stuff to do on @interval
+      unless @last.eql?((@phase * @interval).to_i)
+        @action[:on_tick].call
+        @last = (@phase * @interval).to_i
+      end      
+    end
+     
+  end
+  
+end

data/lib/topaz/midi_sync_output.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+module Topaz
+  
+  # send sync messages via MIDI
+  class MIDISyncOutput
+     
+    def initialize(output, options = {})
+      @output = output
+    end
+    
+    # send a start message
+    def on_start
+      @output.puts(MIDIMessage::SystemRealtime["Start"].new.to_a)
+    end
+
+    # send a stop message
+    def on_stop
+      @output.puts(MIDIMessage::SystemRealtime["Stop"].new.to_a)
+    end
+        
+    # send a clock message
+    def on_tick
+      @output.puts(MIDIMessage::SystemRealtime["Clock"].new.to_a)
+    end
+    
+  end
+  
+end

data/lib/topaz/tempo.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+module Topaz
+  
+  # main tempo class
+  class Tempo
+    
+    extend Forwardable
+    
+    attr_reader :source
+    
+    def_delegators :source, :tempo, :interval, :interval=, :join
+  
+    def initialize(*args, &event)
+      @destinations = []
+
+      if args.first.kind_of?(Numeric)
+        @source = InternalTempo.new(args.shift)
+      end
+      options = args.first
+      
+      initialize_midi_io(options)
+      raise "You must specify an internal tempo rate or an external tempo source" if @source.nil?
+      @source.action = { 
+        :on_start => nil,
+        :on_stop => nil,
+        :on_tick => event,        
+        :destinations => @destinations,
+        :stop_when => nil
+      }
+      @source.interval = options[:interval] unless options.nil? || options[:interval].nil? 
+    end
+    
+    # this will change the tempo
+    #
+    # be warned, in the case that external midi tempo is being used, this will switch to internal 
+    # tempo at the desired rate
+    #
+    def tempo=(val)
+      if @source.respond_to?(:tempo=)
+        @source.tempo = val
+      else
+        @source = InternalTempo.new(tempo, @action)
+      end 
+    end
+    
+    # pass in a callback that is called when start is called
+    def on_start(&block)
+      @source.action[:on_start] = block
+    end
+
+    # pass in a callback that is called when stop is called
+    def on_stop(&block)
+      @source.action[:on_stop] = block
+    end
+    
+    # pass in a callback which will 
+    def stop_when(&block)
+      @source.action[:stop_when] = block
+    end
+        
+    # this will start the generator
+    #
+    # in the case that external midi tempo is being used, this will wait for a start 
+    # or clock message
+    #
+    def start(options = {})
+      @start_time = Time.now
+      @destinations.each { |dest| dest.on_start }
+      @source.start(options)
+    end
+    
+    # this will stop tempo
+    def stop(options = {})
+      @destinations.each { |dest| dest.on_stop }
+      @source.stop(options)
+    end
+    
+    # seconds since start was called
+    def start_time
+      @start_time.nil? ? nil : (Time.now - @start_time).to_f
+    end
+    alias_method :time_since_start, :start_time
+    
+    private
+        
+    def initialize_midi_io(args)
+      ports = args.kind_of?(Hash) ? args[:midi] : args
+      unless ports.nil?
+        if ports.kind_of?(Array) 
+          ports.each { |port| initialize_midi_io(port) }
+        elsif ports.type.eql?(:input) && @source.nil?
+          @source = ExternalMIDITempo.new(ports) 
+        elsif ports.type.eql?(:output)
+          @destinations << MIDISyncOutput.new(ports)
+        end
+      end
+    end    
+    
+  end
+  
+end

data/lib/topaz/tempo_calculator.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+module Topaz
+  
+  class TempoCalculator
+    
+    attr_reader :tempo, :timestamps
+    
+    def initialize(tempo = nil)
+      @tempo = tempo
+      @timestamps = []
+      @counter = 0
+    end
+    
+    # analyse the tempo based on the last 6 ticks
+    def find_tempo
+      tempo = nil
+      diffs = []
+      @timestamps.shift while @timestamps.length > 6
+      @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
+    end
+    
+    private
+    
+    # convert the raw tick intervals to bpm
+    def ppq24_millis_to_bpm(ppq24)
+      quarter_note = (ppq24 * 24.to_f)
+      minute = (60 * 1000) # one minute in millis
+      minute/quarter_note
+    end
+    
+  end
+  
+end

data/lib/topaz.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+#
+# MIDI syncable tempo module in Ruby
+# (c)2011 Ari Russo and licensed under the Apache 2.0 License
+# 
+
+require 'forwardable'
+require 'gamelan'
+require 'midi-eye'
+require 'midi-message'
+
+require 'topaz/external_midi_tempo'
+require 'topaz/internal_tempo'
+require 'topaz/midi_sync_output'
+require 'topaz/tempo_calculator'
+require 'topaz/tempo'
+
+module Topaz
+  
+  VERSION = "0.0.1"
+  
+end

data/test/config.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+module TestHelper::Config
+
+  include UniMIDI
+
+  # adjust these constants to suit your hardware configuration
+  # before running tests
+
+  TestInput = Input.first # this is the device you wish to use to test input
+  TestOutput = Output.first # likewise for output
+
+end

data/test/helper.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+dir = File.dirname(File.expand_path(__FILE__))
+$LOAD_PATH.unshift dir + '/../lib'
+
+require 'test/unit'
+require 'topaz'
+
+module TestHelper
+	
+  
+end
+
+require File.dirname(__FILE__) + '/config'

data/test/test_internal_tempo.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'helper'
+
+class InternalTempoTest < Test::Unit::TestCase
+
+  include Topaz
+  include TestHelper
+  
+  def test_stop_when
+    i = 0
+    count_to = 5
+    
+    tempo = Tempo.new(120) { i += 1 }
+    tempo.stop_when { i.eql?(count_to) }
+    tempo.start
+    
+    assert_equal(count_to, i)
+  end
+  
+  def test_timer
+    i = 0
+    count_to = 5
+    
+    tempo = Tempo.new(60) { i += 1 }
+  end
+
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: midi-topaz
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Ari Russo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-26 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: gamelan
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: midi-message
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: midi-eye
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.7
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: unimidi
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.10
+  type: :runtime
+  version_requirements: *id004
+description: MIDI syncable tempo in Ruby
+email: 
+- ari.russo@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/topaz.rb
+- lib/topaz/midi_sync_output.rb
+- lib/topaz/internal_tempo.rb
+- lib/topaz/tempo_calculator.rb
+- lib/topaz/external_midi_tempo.rb
+- lib/topaz/tempo.rb
+- test/helper.rb
+- test/config.rb
+- test/test_internal_tempo.rb
+- LICENSE
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/arirusso/topaz
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: midi-topaz
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: MIDI syncable tempo in Ruby
+test_files: []
+