diamond 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e4b95fbd189a76487319f77e97e6d645a75e4dac
+  data.tar.gz: 608fb59532ddca113ea6c29d68ffcbb34211696e
+SHA512:
+  metadata.gz: eb1157bc6dbf55bd3d2b75808a3fd5d12d75db4467d40e42b72b5e7963fe45505ffa9f294417377d354fa1f662d23a86c7e10e0c4eba64084078cf80c197a34d
+  data.tar.gz: fd6dddb843a56ef77845a04155cd99550e60033953fc407e15d0434fd74503777103513fb2c6f06119978a2bcb16f2f679deb9c892bae5dbf7316cefed24dd70

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011-2014 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.md

@@ -0,0 +1,126 @@
+# Diamond
+
+[MIDI arpeggiator](http://en.wikipedia.org/wiki/Arpeggiator#Arpeggiator) in Ruby
+
+![diamond](http://img256.imageshack.us/img256/4514/diamondd.jpg)
+
+## Features
+
+* Classic arpeggiator functionality
+* [OSC](http://en.wikipedia.org/wiki/Open_Sound_Control) and MIDI remote control
+* MIDI clock IO
+* Suited to [live coding](http://en.wikipedia.org/wiki/Live_coding)
+* Multiplex clocks and arpeggiators
+* Preset and curstom arpeggio pattern algorithms 
+
+## Installation
+
+`gem install diamond`
+  
+  or with Bundler, add this to your Gemfile
+  
+`gem "diamond"` 
+  
+## Usage
+
+```ruby
+require "diamond"
+```
+
+First, select a MIDI output using [unimidi](https://github.com/arirusso/unimidi). ([more about that...](http://tx81z.blogspot.com/2011/10/selecting-midi-device-with-unimidi.html))
+
+```ruby
+@output = UniMIDI::Output.gets
+```
+
+The Diamond arpeggiator has a number of [optional parameters](http://rubydoc.info/github/arirusso/diamond/master/Diamond/Arpeggiator:initialize).  For this example, here's a straightforward setup
+
+```ruby
+options = { 
+  :gate => 90, 
+  :interval => 7,
+  :midi => @output,
+  :pattern => "UpDown",
+  :range => 4,     
+  :rate => 8
+}
+
+arpeggiator = Diamond::Arpeggiator.new(options) 
+```
+
+Create a clock object, passing in a tempo value. In this case the tempo will be 138 BPM
+
+```ruby
+clock = Diamond::Clock.new(138)
+```
+
+Point the clock to the arpeggiator
+
+```ruby
+clock << arpeggiator
+```
+
+Of course, an arpeggiator needs notes to work with. You can use a MIDI input for that. ([see example](http://github.com/arirusso/diamond/blob/master/examples/midi_note_input.rb)). However, again for the sake of simplicity here's a chord in Ruby
+
+```ruby
+chord = ["C3", "G3", "Bb3", "A4"]
+```
+
+Use `Arpeggiator#add` and `Arpeggiator#remove` to change the notes that the arpeggiator sees. (`Arpeggiator#<<` is the same as add)  
+
+```ruby
+arpeggiator.add(chord)   
+arpeggiator << "C5"
+```
+
+Now we'll start the clock and arpeggiator.  
+
+Note that by default, the clock will run in a background thread. If you're working in a [PRY](http://pryrepl.org)/[IRB](http://en.wikipedia.org/wiki/Interactive_Ruby_Shell)/etc this will allow you to continue to code while the arpeggiator runs. To start in the *foreground*, pass `:focus => true` to `Clock#start`.
+
+```ruby
+clock.start
+```
+
+All of the [arpeggiator options](http://rubydoc.info/github/arirusso/diamond/master/Diamond/Arpeggiator:initialize) can be controlled on the on the fly
+
+```ruby
+arpeggiator.rate = 16
+arpeggiator.gate = 20  
+arpeggiator.remove("C5", "A4")
+```
+
+[This screencast video](http://vimeo.com/25983971) shows Diamond being live coded in this way.  (Note that the API has changed a bit since 2011 when the video was made).
+
+This [blog post](http://tx81z.blogspot.com/2011/07/live-coding-with-diamond.html) explains what is happening in the video.
+
+#### Posts
+
+* [Introduction](http://tx81z.blogspot.com/2011/07/diamond-midi-arpeggiator-in-ruby.html)
+* [Live coding Diamond and syncing multiple arpeggiators to each other](http://tx81z.blogspot.com/2011/07/live-coding-with-diamond.html)
+* [A note about live coding in IRB with OSX](http://tx81z.blogspot.com/2011/09/note-about-live-coding-in-irb-with-osx.html)
+
+#### Examples
+
+* [Control via OSC](http://github.com/arirusso/diamond/blob/master/examples/osc_control.rb)
+* [Define a Pattern](http://github.com/arirusso/diamond/blob/master/examples/define_pattern.rb)
+* [Feed notes to Diamond using a MIDI controller or other input](http://github.com/arirusso/diamond/blob/master/examples/midi_note_input.rb)
+* [Feed notes to Diamond using MIDI message objects](http://github.com/arirusso/diamond/blob/master/examples/midi_message_objects.rb)
+* [Sync multiple Arpeggiator instances to each other](http://github.com/arirusso/diamond/blob/master/examples/sync_multiple_arps.rb)
+* [Sync Diamond to external MIDI clock](http://github.com/arirusso/diamond/blob/master/examples/midi_clock_sync.rb)
+* [Use Diamond as a master MIDI clock](http://github.com/arirusso/diamond/blob/master/examples/midi_clock_output.rb)
+
+[More...](http://github.com/arirusso/diamond/blob/master/examples)
+ 
+## Other Documentation
+
+* [rdoc](http://rubydoc.info/github/arirusso/diamond)
+
+## Author
+
+* [Ari Russo](http://github.com/arirusso) <ari.russo at gmail.com>
+
+## License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011-2014 Ari Russo

data/lib/diamond.rb

@@ -0,0 +1,35 @@
+#
+# Diamond
+#
+# MIDI arpeggiator in Ruby
+# (c)2011-2014 Ari Russo and licensed under the Apache 2.0 License
+#
+
+# libs 
+require "forwardable"
+require "midi-instrument"
+require "midi-message"
+require "osc-ruby"
+require "osc-ruby/em_server"
+require "scale"
+require "sequencer"
+require "topaz"
+require "unimidi"
+
+# modules
+require "diamond/api"
+
+# classes
+require "diamond/arpeggiator"
+require "diamond/clock"
+require "diamond/midi"
+require "diamond/osc"
+require "diamond/pattern"
+require "diamond/sequence"
+require "diamond/sequence_parameters"
+
+module Diamond
+  
+  VERSION = "0.5.1"
+  
+end

data/lib/diamond/api.rb

@@ -0,0 +1,102 @@
+module Diamond
+
+  # Convenience methods for the instrument
+  module API
+
+    # MIDI convenience methods
+    module MIDI
+
+      def self.included(base)
+        base.send(:extend, Forwardable)
+        base.send(:def_delegators, 
+                  :@midi,
+                  :<<,
+                  :add,
+                  :mute,
+                  :mute=,
+                  :omni_on, 
+                  :remove,
+                  :rx_channel, 
+                  :receive_channel,
+                  :rx_channel=,
+                  :receive_channel=,
+                  :toggle_mute,
+                  :tx_channel, 
+                  :transmit_channel,
+                  :tx_channel=,
+                  :transmit_channel=
+                 )
+      end
+
+      # Add a MIDI input
+      # @param [UniMIDI::Input] source
+      # @return [Array<UniMIDI::Input>]
+      def add_midi_source(source)
+        @midi.inputs << source
+      end
+
+      # Remove a MIDI input
+      # @param [UniMIDI::Input] source
+      # @return [Array<UniMIDI::Input>]
+      def remove_midi_source(source)
+        @midi.inputs.delete(source)
+      end
+
+      # MIDI inputs associated with this instrument
+      # @return [Array<UniMIDI::Input>]
+      def midi_sources
+        @midi.inputs
+      end
+
+      # Is the instrument MIDI output muted?
+      # @return [Boolean]
+      def mute?
+        @midi.output.mute?
+      end
+      alias_method :muted?, :mute?
+
+    end
+
+    # Convenience methods dealing with the sequence
+    module Sequence
+
+      def self.included(base)
+        base.send(:extend, Forwardable)
+        base.send(:def_delegators,
+                  :@sequence, 
+                  :sequence, 
+                  :remove_all)
+        base.send(:alias_method, :clear, :remove_all)
+      end
+
+    end
+
+    # Convenience methods dealing with the sequence parameters
+    module SequenceParameters
+
+      def self.included(base)
+        base.send(:extend, Forwardable)
+        base.send(:def_delegators,
+                  :@parameter, 
+                  :gate,
+                  :gate=,
+                  :interval,
+                  :interval=,
+                  :pattern,
+                  :pattern=,
+                  :range,
+                  :range=,
+                  :rate,
+                  :rate=,
+                  :pattern_offset,
+                  :pattern_offset=,
+                  :resolution,
+                  :resolution=,
+                  :transpose,
+                  :transpose=)
+      end
+
+    end
+
+  end
+end

data/lib/diamond/arpeggiator.rb

@@ -0,0 +1,81 @@
+module Diamond
+
+  # The arpeggiator core
+  class Arpeggiator
+
+    include API::MIDI
+    include API::Sequence
+    include API::SequenceParameters
+
+    attr_reader :parameter, :sequence, :sequencer
+
+    # @param [Hash] options
+    # @option options [Fixnum] :gate Duration of the arpeggiated notes. The value is a percentage based on the rate.  If the rate is 4, then a gate of 100 is equal to a quarter note. (default: 75) must be 1..500
+    # @option options [Fixnum] :interval Increment (pattern) over (interval) scale degrees (range) times.  May be positive or negative. (default: 12)
+    # @option options [Array<UniMIDI::Input, UniMIDI::Output>, UniMIDI::Input, UniMIDI::Output] :midi MIDI devices to use
+    # @option options [Array<Hash>] :midi_control A user-defined mapping of MIDI cc to arpeggiator params
+    # @option options [Boolean] :midi_debug Whether to send debug output about MIDI to standard out
+    # @option options [Fixnum] :rx_channel (or :channel) Only respond to input messages to the given MIDI channel. will operate on all input sources. if not included, or nil the arpeggiator will work in omni mode and respond to all messages
+    # @option options [Fixnum] :tx_channel Send output messages to the given MIDI channel despite what channel the input notes were intended for.
+    # @option options [Fixnum] :pattern_offset Begin on the nth note of the sequence (but not omit any notes). (default: 0)
+    # @option options [String, Pattern] :pattern Computes the contour of the arpeggiated melody.  Can be the name of a pattern or a pattern object.
+    # @option options [Fixnum] :range Increment the (pattern) over (interval) scale degrees (range) times. Must be positive (abs will be used). (default: 3)
+    # @option options [Fixnum] :rate How fast the arpeggios will be played. Must be positive (abs will be used). (default: 8, eighth note.) must be 0..resolution
+    # @option options [Fixnum] :resolution Numeric resolution for rhythm (default: 128)   
+    # @option options [Hash] :osc_control A user-defined map of OSC addresses and properties to arpeggiator params
+    # @option options [Fixnum] :osc_port The port to listen for OSC on
+    # @option options [Boolean] :osc_debug Whether to send debug output about OSC to standard out
+    def initialize(options = {}, &block)
+      resolution = options.fetch(:resolution, 128)
+
+      @sequence = Sequence.new
+      @parameter = SequenceParameters.new(@sequence, resolution, options) { @sequence.mark_changed }
+      @sequencer = Sequencer.new
+
+      initialize_midi(options)
+      initialize_osc(options)
+    end
+
+    private
+
+    # Initialize MIDI IO
+    # @param [Hash] options
+    # @option options [Array<UniMIDI::Input, UniMIDI::Output>, UniMIDI::Input, UniMIDI::Output] :midi MIDI devices to use
+    # @option options [Array<Hash>] :midi_control A user-defined mapping of MIDI cc to arpeggiator params
+    # @option options [Boolean] :midi_debug Whether to send debug output about MIDI to standard out
+    # @option options [Fixnum] :rx_channel (or :channel) Only respond to input messages to the given MIDI channel. will operate on all input sources. if not included, or nil the arpeggiator will work in omni mode and respond to all messages
+    # @option options [Fixnum] :tx_channel Send output messages to the given MIDI channel despite what channel the input notes were intended for.
+    # @return [MIDI::Node]
+     def initialize_midi(options = {})
+      receive_channel = options[:rx_channel] || options[:channel]
+      transmit_channel = options[:tx_channel]
+      devices = MIDIInstrument::Device.partition(options[:midi])
+      @midi = MIDI.new(devices, :debug => !!options[:midi_debug], :receive_channel => receive_channel, :transmit_channel => transmit_channel)
+      @midi.enable_output(@sequencer)
+      @midi.enable_note_control(@sequence)
+      @midi.enable_parameter_control(@parameter, options[:midi_control]) if !options[:midi_control].nil?
+      @midi
+    end
+
+    # @param [Hash] options
+    # @option options [Hash] :osc_control A map of OSC addresses and properties
+    # @option options [Fixnum] :osc_port The port to listen for OSC on
+    # @return [OSC::Node]
+    def initialize_osc(options = {})
+      @osc = OSC.new(:debug => !!options[:osc_debug], :server_port => options[:osc_port])
+      @osc.enable_parameter_control(@parameter, options[:osc_control]) if !options[:osc_control].nil?
+      @osc
+    end
+
+    # Emit any note off messages that are currently pending in the queue.  The clock triggers this 
+    # when stopping or pausing
+    # @return [Array<MIDIMessage::NoteOff>]
+    def emit_pending_note_offs
+      messages = @sequence.pending_note_offs
+      @midi.output.puts(*messages)
+      messages
+    end
+
+  end
+
+end

data/lib/diamond/clock.rb

@@ -0,0 +1,88 @@
+module Diamond
+
+  # A wrapper for Sequencer::Clock (and thus Topaz::Tempo) that's geared towards the arpeggiator
+  class Clock
+
+    extend Forwardable
+
+    def_delegators :@clock, :event, :pause, :unpause
+
+    # @param [Fixnum, UniMIDI::Input] tempo_or_input
+    # @param [Hash] options
+    # @option options [Array<UniMIDI::Output>, UniMIDI::Output] :outputs MIDI output device(s)
+    def initialize(*args)
+      @arpeggiators = []
+      @clock = Sequencer::Clock.new(*args)
+    end
+
+    # Start the clock
+    # @param [Hash] options
+    # @option options [Boolean] :blocking Whether to run in the foreground (also :focus, :foreground)
+    # @option options [Boolean] :suppress_clock Whether this clock is a sync-slave
+    # @return [Boolean]
+    def start(options = {})
+      begin
+        @clock.start(options)
+      rescue SystemExit, Interrupt => exception
+        stop
+      end
+    end
+
+    # Stop the clock (and fire the arpeggiator sequencer stop event)
+    # @return [Boolean]
+    def stop
+      @arpeggiators.each { |arpeggiator| arpeggiator.sequencer.event.do_stop }
+      @clock.stop
+      true
+    end
+
+    # Add an arpeggiator to this clock's control
+    # @param [Array<Arpeggiator>, Arpeggiator] arpeggiator
+    # @return [Boolean]
+    def add(arpeggiator)
+      arpeggiators = [arpeggiator].flatten
+      result = arpeggiators.map do |arpeggiator|
+        unless @arpeggiators.include?(arpeggiator)
+          @arpeggiators << arpeggiator
+          reset_tick
+          true
+        else
+          false
+        end
+      end
+      result.any?
+    end
+    alias_method :<<, :add
+
+    # Remove an arpeggiator from this clock's control
+    # @param [Arpeggiator] arpeggiator
+    # @return [Boolean]
+    def remove(arpeggiator)
+      arpeggiators = [arpeggiator].flatten
+      result = arpeggiators.map do |arpeggiator|
+        if @arpeggiators.include?(arpeggiator)
+          @arpeggiators.delete(arpeggiator)
+          reset_tick
+          true
+        else
+          false
+        end
+      end
+      result.any?
+    end
+
+    private
+
+    # Reset the clock's tick event (used when arpeggiators are added or removed)
+    # @return [Array<Arpeggiator>] Arpeggiators that are now actively controlled by this clock
+    def reset_tick
+      @clock.event.tick.clear
+      @arpeggiators.map do |arpeggiator|
+        @clock.event.tick << proc { arpeggiator.sequencer.exec(arpeggiator.sequence) }
+        arpeggiator.sequencer.event.stop { @clock.stop }
+        arpeggiator
+      end
+    end
+  end
+
+end