jsound 0.1.0-java → 0.1.2-java

data/.yardopts

@@ -1,3 +1,5 @@
---readme README.md
+--readme INTRO.md
 --title "JSound: a Ruby wrapper for Java's sound API"
 lib/**/*.rb
+- INTRO.md
+- examples/*.rb

data/INTRO.md

@@ -0,0 +1,159 @@
+Synopsis
+--------
+
+JSound provides cross-platform [MIDI](http://en.wikipedia.org/wiki/Musical_Instrument_Digital_Interface) support for Ruby.
+
+Java's cross-platform standard library includes a
+[sound API for MIDI and sampled sound](http://download.oracle.com/javase/tutorial/sound/index.html).
+JSound builds on this API and provides a Ruby interface via [JRuby](http://jruby.org).
+
+For now, JSound is focusd on use of the [javax.sound.midi API](http://download.oracle.com/javase/7/docs/api/javax/sound/midi/package-summary.html)
+in Ruby scripts and applications.
+Support for the [javax.sound.samples API](http://download.oracle.com/javase/7/docs/api/javax/sound/sampled/package-summary.html)
+may arrive in the future.
+
+<br>
+project info @ http://github.com/adamjmurray/jsound
+
+<br>
+Core Concepts
+-------------
+
+### Messages ###
+
+Messages repesent musical events, such as a note being played or a musical parameter changing (vibrato, FX level, pitch bend, etc).
+
+JSound provides direct support for various MIDI message, which can be found in the {JSound::Midi::Messages} module.
+
+Generic support for other message types is provided by the {JSound::Midi::Message} class.
+
+<br>
+### Devices ###
+
+Devices send messages to one another to communicate musical information. There are 3 general categories:
+
+* __Input Devices__ receive messages from external hardware (e.g. keyboards, digital drums) or other software
+* __Output Devices__ send messages to external hardware (e.g. synthesizers) or other software
+* __Custom Devices__ process messages in arbitrary ways (e.g. generate, record, transform, route)
+
+JSound provides the input and output devices via the {JSound::Midi::INPUTS} and {JSound::Midi::OUTPUTS} constants.
+INPUTS and OUTPUTS are {JSound::Midi::DeviceList}s, which provide methods for looking up specific devices.
+
+You make your own custom devices with Ruby by subclassing the {JSound::Midi::Device} class,
+or use some of the custom devices provided in the {JSound::Midi::Devices} module.
+
+<br>
+### Device Graphs ###
+
+In order to do something useful, devices must be connected together. Input and Output devices interact with the
+outside world but don't do anything useful by themselves. Custom devices have practically unlimited
+possibilities, but are useless without input or output.
+
+To connect devices together to form a device graph, we use the {JSound::Midi::Device#>>} operator.
+
+Examples:
+
+record input:
+    input >> recorder
+
+generate output:
+    generator >> output
+
+transform a MIDI stream:
+    input >> transformer >> output
+
+
+<br>
+Using JSound
+------------
+
+0. Install JRuby 1.5 or 1.6, either:
+   - via manual installation
+      - Download and unpack the [current binary version of JRuby](http://jruby.org/download)
+      - Put the JRuby bin folder on your PATH
+   - or via [rvm](https://rvm.beginrescueend.com/) (adjust version number as desired):
+
+             rvm install jruby-1.6.2
+             rvm use jruby-1.6.2
+
+0. Install JSound
+
+         jgem install jsound
+
+0. Try the examples (monitor.rb prints any input it receives, try playing a MIDI keyboard):
+
+         mkdir tmp
+         cd tmp
+         jgem unpack jsound
+         cd jsound-{version}
+         jruby examples/list_devices.rb
+         jruby examples/monitor.rb
+         ...
+
+0. Explore this documentation
+
+
+<br>
+Examples
+--------
+
+* {file:examples/list_devices.rb list_devices.rb}
+
+* {file:examples/monitor.rb monitor.rb}
+
+* {file:examples/play_notes.rb play_notes.rb}
+
+* {file:examples/transpose.rb transpose.rb}
+
+* {file:examples/harmonize.rb harmonize.rb}
+
+* {file:examples/harmonize2.rb harmonize2.rb}
+
+
+ <br>
+Notes
+-----
+
+### Opening Devices ###
+
+Input and output devices will not function until they are opened via {JSound::Midi::Device#open}.
+If an input or output device does not appear to be working, you probably forgot to open it.
+
+Some of the {JSound::Midi::DeviceList} methods will automatically open the device for you.
+The {JSound::Midi::DeviceList#method_missing} behavior for DeviceList provides a convenient way to
+find and automatically open devices.
+
+
+<br>
+### OS X ###
+
+#### IAC Driver ####
+By enabling the IAC (inter-application communication) driver, you can easily interface with any MIDI-enabled application:
+
+0. Run to /Applications/Utilities/Audio MIDI Setup
+
+0. In the menu, select: Window &rarr; Show MIDI Window
+
+0. Double click IAC Driver
+
+0. Check the box where it says "Device is online"
+
+Now JSound should be able to locate an "IAC Driver" input and output device.
+
+You can also add additional MIDI ports here, to work with multiple applications simultaneously.
+
+#### Output ####
+
+OS X does not provide a default MIDI output device, so you will need to take some extra steps to hear anything.
+
+Typically, you'll want to route MIDI to your music production environment (Logic, Reason, Live, etc) using the IAC driver.
+
+If you don't have a music production environment, you can use the free program SimpleSynth as an output:
+
+0. Download SimpleSynth from http://notahat.com/simplesynth
+
+0. Run SimpleSynth
+
+0. Select "SimpleSynth virtual input"
+
+0. Open the SimpleSynth output device in JSound (i.e. Midi::OUTPUTS.SimpleSynth)

data/README.md

@@ -1,8 +1,9 @@
 JSound: a Ruby wrapper for the Java sound API
 =============================================
 
-This library requires [JRuby](http://jruby.org)
-and currently only supports the [MIDI API](http://java.sun.com/j2se/1.5.0/docs/api/javax/sound/midi/package-summary.html)
+JSound provides cross-platform [MIDI](http://en.wikipedia.org/wiki/Musical_Instrument_Digital_Interface) support for Ruby.
+
+This library requires [JRuby](http://jruby.org).
 
 
 
@@ -13,65 +14,25 @@ Home:     http://github.com/adamjmurray/jsound
 
 Author:   Adam Murray (adam@compusition.com)
 
-License:  Distributed under a permissive BSD-style license, see LICENSE.txt
+License:  Distributed under a permissive BSD-style license, [see LICENSE.txt](LICENSE.txt)
 
 
 
 Getting started
 ---------------
 
-0. Install JRuby 1.5 or 1.6, either:
-   - via manual installation
-      - Download and unpack the [current binary version of JRuby](http://jruby.org/download)
-      - Put the JRuby bin folder on your PATH
-   - or via [rvm](https://rvm.beginrescueend.com/) (adjust version number as desired):
-
-             rvm install jruby-1.6.2
-             rvm use jruby-1.6.2
-
-0. Install JSound
-
-         jgem install jsound
-
-0. Try the examples (monitor.rb prints any input it receives, try playing a MIDI keyboard):
-
-         jruby examples/list_devices.rb
-         jruby examples/monitor.rb
-     
-0. Take a look at the comments in examples/notes.rb for info on:
-   - routing MIDI inputs to MIDI outputs
-   - generating MIDI events and sending them to an output
+See [the documentation's introduction](INTRO.md).
 
 
 
 Documentation
 -------------
 
-Gem: http://rubydoc.info/gems/jsound/0.0.1/frames
+Gem: http://rubydoc.info/gems/jsound/0.1.2/frames
 
 Latest for source: http://rubydoc.info/github/adamjmurray/jsound/master/frames
 
 
-Notes
------
-
-### OS X ###
-
-By enabling the IAC (inter-application communication) driver, you can easily interface with any MIDI-enabled application:
-
-0. Run to /Applications/Utilities/Audio MIDI Setup
-
-0. In the menu, select: Window → Show MIDI Window
-
-0. Double click IAC Driver
-
-0. Check the box where it says "Device is online"
-
-Now JSound should be able to locate an "IAC Driver" input and output device.
-
-You can also add additional MIDI ports here, to work with multiple applications simultaneously.
-
-
 
 Development Notes
 -----------------
@@ -90,7 +51,22 @@ and to quickly check compatibility with multiple JRuby versions via rvm:
      yard
      open doc/frames.html
 
+or, to automatically refresh the documentation as you work:
+
+      yard server -r
+      open http://localhost:8808
+
 
 ### Project Roadmap ###
 
-https://www.pivotaltracker.com/projects/85719
+https://www.pivotaltracker.com/projects/85719
+
+
+Changelog
+---------
+
+* June 18, 2011, version 0.1.2
+    - added a "Hash of mappings" feature to Transformer, for easy implementation of simple transformation patterns
+    - improved examples
+    - got rid of the Repeater device and built its functionality into the base Device
+    - added #output= and #>> to DeviceList, to construct parallel paths in device graphs

data/examples/harmonize.rb

@@ -0,0 +1,25 @@
+#
+# EXAMPLE: Harmonize pitches by adding a second transposed pitch
+#
+require 'rubygems'
+require 'jsound'
+include JSound
+
+# open the input & output matching the first & second command line arg, or default to the first available
+input  = ARGV[0] ? Midi::INPUTS / ARGV[0] : Midi::INPUTS.open_first
+output = ARGV[1] ? Midi::OUTPUTS/ ARGV[1] : Midi::OUTPUTS.open_first
+
+harmonizer = Midi::Devices::Transformer.new do |message|
+  if message.respond_to? :pitch
+    transposed = message.clone # messages are mutable, so we have to clone them to keep the original intact
+    transposed.pitch += 3 # transpose up a minor third
+    [message, transposed]
+
+  else # pass through everything else
+    message
+  end
+end
+
+input >> harmonizer >> output
+
+sleep 5 while true # force script to keep running

data/examples/harmonize2.rb

@@ -0,0 +1,23 @@
+#
+# EXAMPLE: Harmonize pitches by adding a second transposed pitch
+#
+# Alternate implementation, compare with the harmonize.rb example.
+# This approach simplifies the transformer, but requires a more complex device graph.
+#
+require 'rubygems'
+require 'jsound'
+include JSound
+
+# open the input & output matching the first & second command line arg, or default to the first available
+input  = ARGV[0] ? Midi::INPUTS / ARGV[0] : Midi::INPUTS.open_first
+output = ARGV[1] ? Midi::OUTPUTS/ ARGV[1] : Midi::OUTPUTS.open_first
+
+pass_through = Midi::Device.new
+transposer = Midi::Devices::Transformer.new :pitch => lambda{|p| p + 3 }  # transpose up a minor third
+
+input >> Midi.DeviceList(pass_through, transposer) >> output
+# connecting a custom device list creates a graph of parallel chains:
+# input ==> pass_through ==> output
+# input ==> transposer ==> output
+
+sleep 5 while true # force script to keep running

data/examples/launchpad/launchpad_generator.rb

@@ -1,37 +1,11 @@
-# A device for controlling a Novation Launchpad
-# To try this example, do this from the top-level project source folder
-=begin
-
-  jirb -I lib
-  require 'jsound'
-  require 'examples/launchpad/launchpad_generator.rb'
-  include JSound::Midi
-  lp = OUTPUTS.Launchpad
-  g = LaunchpadGenerator.new
-  g >> lp
-
-  g.all_off
-    
-  # Make the top left grid button green:
-  g.grid(0,0,:green)
-  
-  # Make the mixer button red:
-  g.mixer(:red)
-  
-  # Make the second 'scene launch' (rightmost column of buttons) orange:
-  g.scene_launch(2,:orange)
-  
-  # and we can also do yellow:
-  g.grid(1,1,:yellow)
-  
-  # and arbitrary mixtures of green and red LEDs (brightness levels for each range from 0-3)
-  g.grid(2,2,[1,1])
-    
-  at_exit { g.all_off } # this will turn everything off when you exit irb
-  
-=end
+#
+# EXAMPLE: A device for controlling a Novation Launchpad
+#
+require 'rubygems'
+require 'jsound'
+include JSound
 
-class LaunchpadGenerator < JSound::Midi::Devices::Generator
+class LaunchpadGenerator < Midi::Devices::Generator
   
   def grid(x,y,color=3)
     x = clip(x,0,15)
@@ -107,5 +81,33 @@ class LaunchpadGenerator < JSound::Midi::Devices::Generator
     r = clip(r.to_i,0,3)
     return 16*g + r
   end
-  
-end
+
+end
+
+
+gen = LaunchpadGenerator.new
+gen >> Midi::OUTPUTS.Launchpad
+
+# clear all the lights at the start of the script
+gen.all_off
+# ... and at the end
+at_exit { gen.all_off }
+
+8.times do |y|
+  8.times do |x|
+    gen.grid x, y, :green
+    sleep 0.02
+  end
+end
+
+8.times do |n|
+  gen.control_row n, :amber
+  gen.scene_launch n, :red
+  sleep 0.2
+end
+
+
+# Other things to try:
+# g.mixer(:red) # make the mixer button red
+# g.grid(2,2,[1,1]) # arbitrary mixture of green and red LEDs (brightness levels for each range from 0-3)
+

data/examples/launchpad/{launchpad.rb → launchpad_monitor.rb}

@@ -1,16 +1,14 @@
-#!/usr/bin/env jruby --debug
+#
+# EXAMPLE: monitoring Novation Launchpad input using custom Messages
+#
+# Note: I have to hit a button on the top row of my Launchpad before I can receive any input.
+#
 require 'rubygems'
 require 'jsound'
-include JSound::Midi
-
-# A quick prototype of monitoring input from a Novation Launchpad, 
-# after translating it to something more meaningful than the raw MIDI messages.
-
-# Note: I have to hit a button on the top row of my Launchpad before I can receive any input.
-
+include JSound
 
 # A higher-level representation of the messages coming from the Launchpad
-class LaunchpadMessage < Messages::Message
+class LaunchpadMessage < Midi::Message
   def initialize(button_group, position, pressed, channel=0, source=nil)
     @type = :launchpad_button
     @button_group = button_group
@@ -23,8 +21,8 @@ class LaunchpadMessage < Messages::Message
 end
 
 # A device that converts the lower-level MIDI messages into LaunchpadMessages
-class LaunchadTranslator < Devices::Device  
-  def <=(message)
+class LaunchadTranslator < Midi::Device
+  def message(message)
     case message.type    
 
     when :control_change
@@ -53,13 +51,8 @@ class LaunchadTranslator < Devices::Device
   end  
 end
 
-
-# And now that those classes are defined, 
+# And now that those classes are defined,
 # just hook up the Launchpad to a monitor, with the translator in between:
-INPUTS.Launchpad >> LaunchadTranslator.new >> Devices::Monitor.new
+Midi::INPUTS.Launchpad >> LaunchadTranslator.new >> Midi::Devices::Monitor.new
 
-
-# force the script to keep running (MIDI devices run in a background thread)
-while(true)
-  sleep 5
-end
+sleep 5 while true # force script to keep running

data/examples/list_devices.rb

@@ -1,6 +1,7 @@
-#!/usr/bin/env jruby
+#
+# EXAMPLE: list all available devices
+#
 require 'rubygems'
 require 'jsound'
-include JSound::Midi
 
-puts DEVICES
+puts JSound::Midi::DEVICES

data/examples/monitor.rb

@@ -1,15 +1,15 @@
-#!/usr/bin/env jruby
+#
+# EXAMPLE: Monitor all MIDI inputs
+#
 require 'rubygems'
 require 'jsound'
-include JSound::Midi
+include JSound
 
-INPUTS.each do |input| 
+monitor = Midi::Devices::Monitor.new
+
+for input in Midi::INPUTS
   input.open
-  input >> Devices::Monitor.new
+  input >> monitor
 end
 
-# force the script to keep running (MIDI devices run in a background thread)
-while(true)
-  sleep 5
-end
-  
+sleep 5 while true # force script to keep running

data/examples/play_notes.rb

@@ -0,0 +1,20 @@
+#
+# EXAMPLE: generate and play some notes
+#
+require 'rubygems'
+require 'jsound'
+include JSound
+
+generator = Midi::Devices::Generator.new
+
+# open the output matching the first command line arg, or default to the first available
+output = ARGV[0] ? Midi::OUTPUTS/ ARGV[0] : Midi::OUTPUTS.open_first
+
+generator >> output
+
+13.times do |interval|
+  pitch = 60+interval
+  generator.note_on pitch, 100
+  sleep 0.5
+  generator.note_off pitch
+end

data/examples/transpose.rb

@@ -0,0 +1,21 @@
+#
+# EXAMPLE: using a Transformer to transpose pitches up 2 octaves
+#
+require 'rubygems'
+require 'jsound'
+include JSound
+
+# open the input & output matching the first & second command line arg, or default to the first available
+input  = ARGV[0] ? Midi::INPUTS / ARGV[0] : Midi::INPUTS.open_first
+output = ARGV[1] ? Midi::OUTPUTS/ ARGV[1] : Midi::OUTPUTS.open_first
+
+# Using a block like this is most flexible way to implement a tranformer.
+# This particular transformer has a nice shortcut. See the harmonize2.rb example
+transposer = Midi::Devices::Transformer.new do |message|
+  message.pitch += 24 if message.respond_to? :pitch # transpose up two octaves (24 semitones)
+  message
+end
+
+input >> transposer >> output
+
+sleep 5 while true # force script to keep running

data/lib/jsound/midi.rb

@@ -16,7 +16,6 @@ require 'jsound/midi/devices/input_device'
 require 'jsound/midi/devices/output_device'
 require 'jsound/midi/devices/monitor'
 require 'jsound/midi/devices/recorder'
-require 'jsound/midi/devices/repeater'
 require 'jsound/midi/devices/transformer'
 
 require 'jsound/midi/device_list'

data/lib/jsound/midi/device.rb

@@ -4,7 +4,7 @@ module JSound
     # A device that can transmit and/or receive messages (typically MIDI messages).
     # This default implementation simply passes through all messages.
     class Device
-      include JSound::Mixins::TypeFromClassName
+      include JSound::TypeFromClassName
 
       # Open the device and allocate the needed resources so that it can send and receive messages
       # @note this operation is typically only relevant for Java-based devices such as {Devices::InputDevice} and {Devices::OutputDevice}
@@ -48,12 +48,17 @@ module JSound
         self.output= device
       end
 
-      # Send a message to this device
+      # Send a message to this device and pass it through to any output(s)
       # @param [Message]
       # @see #<=
       def message(message)
-        # default behavior is to pass the message to any connected output
-        @output.message(message) if @output
+        if @output.respond_to? :each
+          for device in @output
+            device.message(message)
+          end
+        elsif @output
+          @output.message(message)
+        end
       end
 
       # send a message to this device. shortcut for {#message}

data/lib/jsound/midi/device_list.rb

@@ -14,6 +14,12 @@ module JSound
         @devices = list
       end
 
+      def each
+        for device in devices
+          yield device
+        end
+      end
+
       # Find the first {Device} matching the criteria
       #
       # @param criteria  matches description against for a Regexp argument, matches the device field against the value for a Hash argument, otherwise checks for an equal description
@@ -103,6 +109,14 @@ module JSound
         open @devices.first
       end
 
+      # Connect the output to all devices in this device list
+      def output= output
+        for device in devices
+          device.output = output
+        end
+      end
+      alias :>> :output=
+
       def to_s
         @devices.join("\n")
       end
@@ -153,5 +167,10 @@ module JSound
 
     end
 
+    def DeviceList(*devices)
+      DeviceList.new(devices)
+    end
+    module_function :DeviceList
+
   end
 end

data/lib/jsound/midi/devices/generator.rb

@@ -3,7 +3,7 @@ module JSound
     module Devices
 
       # A device which provides methods for generating MIDI command messages.
-      # See JSound::Midi::Messages::Builder for the available methods.
+      # @see JSound::Midi::MessageBuilder
       class Generator < Device
 
         # For all the methods defined in the MessageBuilder module (note_on, pitch_bend, control_change, etc),

data/lib/jsound/midi/devices/recorder.rb

@@ -45,6 +45,10 @@ module JSound
         end
         alias recording? open?
 
+        def output= device
+          raise "#{self.class} cannot be assigned an output"
+        end
+
         def message(message)
           @messages_with_timestamps << [message, Time.now.to_i] if recording?
         end

data/lib/jsound/midi/devices/transformer.rb

@@ -4,21 +4,47 @@ module JSound
 
       class Transformer < Device
 
+        # A Hash of mappings, with entries in the format {:message_attribute => lambda{|attribute| ... } }
+        attr_accessor :mappings
+
+        # If true, messages will be automatically cloned when received by this device.
+        # Messages are mutable, so in many cases it's important to clone a message before changing it.
+        attr_accessor :clone
+        
         # The transformation block: a lambda that takes a message and returns
         # either a transformed message or an Enumerable list of messages
-        attr_accessor :message_processor
+        attr_accessor :transform
 
-        def initialize(&message_processor)
-          @message_processor = message_processor
+        # @param mappings [Hash] a Hash of mappings (see {#mappings}).
+        #          When not nil, {#clone} will be automatically set to true.
+        #          Set {#clone} to false by including the entry \{:clone => false}
+        # @param &transform see {#transform}
+        def initialize(mappings=nil, &transform)
+          @clone = !!mappings.fetch(:clone, true) if mappings
+          mappings.delete :clone if mappings
+          @mappings = mappings
+          @transform = transform
         end
 
         def message(message)
-          if @output and @message_processor
-            transformed_message = @message_processor.call(message)
-            if transformed_message.is_a? Enumerable
-              transformed_message.each{|m| @output.message(m) }
-            else
-              @output.message(transformed_message) if transformed_message
+          message = message.clone if @clone
+
+          for attr, mapping in @mappings
+            setter = "#{attr}="
+            message.send setter, mapping[message.send attr] if message.respond_to? attr and message.respond_to? setter
+          end if @mappings
+
+          if @output
+            if @transform
+              message = @transform[message]
+              if message.is_a? Enumerable
+                message.each{|m| @output.message(m) }
+              else
+                super(message) if message
+              end
+
+            elsif @clone or !@mappings.empty?
+              super(message)
             end
           end
         end

data/lib/jsound/midi/message.rb

@@ -6,7 +6,7 @@ module JSound
     # See http://www.midi.org/techspecs/midimessages.php
     # for info on how the MIDI spec defines these messages.
     class Message
-      include JSound::Mixins::TypeFromClassName
+      include JSound::TypeFromClassName
 
       # The MIDI input {Device} which received this message.
       attr_reader :source

data/lib/jsound/type_from_class_name.rb

@@ -1,4 +1,4 @@
-module JSound::Mixins
+module JSound
 
   # Provides a default implementation of .type for the Class, based on the class name.
   module TypeFromClassName

data/spec/jsound/midi/device_spec.rb

@@ -52,10 +52,21 @@ module JSound::Midi
         output.should_receive(:message).with('the_message')
         device.message 'the_message'
       end
+
+      it "should pass send the messages to all connected outputs" do
+        output1 = mock "device1"
+        output2 = mock "device2"
+        device >> [output1, output2]
+
+        output1.should_receive(:message).once.with :the_message
+        output2.should_receive(:message).once.with :the_message
+        device.message :the_message
+      end
+
     end
 
     describe '#<=' do
-      it 'should behave like #send_message' do
+      it 'should behave like #message' do
         device >> output
         output.should_receive(:message).with('the_message')
         device <= 'the_message'

data/spec/jsound/midi/devices/recorder_spec.rb

@@ -84,5 +84,17 @@ module JSound::Midi::Devices
       end
     end
 
+    describe "#output=" do
+      it "should raise an error, since outputs cannot have outputs assigned" do
+        lambda{ recorder.output = Device.new }.should raise_error
+      end
+    end
+
+    describe "#>>" do
+      it "should raise an error, since outputs cannot have outputs assigned" do
+        lambda{ device >> Device.new }.should raise_error
+      end
+    end
+
   end
 end

data/spec/jsound/midi/devices/transformer_spec.rb

@@ -12,6 +12,35 @@ module JSound::Midi
           output.should_receive(:message).once.with MessageBuilder.note_on(72,100)
           transformer.message MessageBuilder.note_on(60,100)
         end
+
+        it "modifies message properties based on the Hash of mappings passed to .new" do
+          transformer = Transformer.new({
+            :attr1 => lambda{|attr| attr+1 },
+            :attr2 => lambda{|attr| attr-1 },
+          })
+          message = mock 'message'
+          message.stub!(:attr1).and_return 1
+          message.stub!(:attr2).and_return 5
+
+          message.should_receive(:attr1=).once.with 2
+          message.should_receive(:attr2=).once.with 4
+          transformer.message message
+        end
+
+        it "automatically clones the message when constructed with a Hash of mappings" do
+          transformer = Transformer.new({ :attr1 => lambda{|attr| attr+1 } })
+          message = mock 'message'
+          message.should_receive :clone
+          transformer.message message
+        end
+
+        it "does not clone the message when constructed with a Hash of mappings that includes {:clone => false}" do
+          transformer = Transformer.new({ :attr1 => lambda{|attr| attr+1 }, :clone => false })
+          message = mock 'message'
+          message.should_not_receive :clone
+          transformer.message message
+        end
+
       end
 
     end

data/spec/jsound/midi/devlice_list_spec.rb

@@ -20,6 +20,14 @@ module JSound::Midi
       end
     end
 
+    describe "#each" do
+      it "yields each device" do
+        yielded = []
+        device_list.each{|device| yielded << device }
+        yielded.should == devices
+      end
+    end
+
     describe "#open" do
       it "acts like #find and also opens the device" do
         device2.should_receive :open
@@ -43,6 +51,26 @@ module JSound::Midi
       end
     end
 
+    describe "#output=" do
+      it "passes the argument to each device#open" do
+        output = mock "output"
+        device1.should_receive(:output=).with output
+        device2.should_receive(:output=).with output
+        device3.should_receive(:output=).with output
+        device_list.output = output
+      end
+    end
+
+    describe "#>>=" do
+      it "acts like #output=" do
+        output = mock "output"
+        device1.should_receive(:output=).with output
+        device2.should_receive(:output=).with output
+        device3.should_receive(:output=).with output
+        device_list >> output
+      end
+    end
+
     describe "#method_missing" do
       it "acts like #/ for unimplemented methods" do
         device1.should_receive(:open)

data/spec/jsound/type_from_class_name_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-module JSound::Mixins
+module JSound
   describe TypeFromClassName do
 
     context "including_class#type" do      

metadata

@@ -2,7 +2,7 @@
 name: jsound
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.2
 platform: java
 authors: 
 - Adam Murray
@@ -10,10 +10,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-16 00:00:00 Z
+date: 2011-06-18 00:00:00 Z
 dependencies: []
 
-description: 
+description: A Ruby interface for Java's javax.sound API. Runs on the JVM via JRuby.
 email: adam@compusition.com
 executables: []
 
@@ -22,9 +22,10 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- Rakefile
+- INTRO.md
 - README.md
 - LICENSE.txt
+- Rakefile
 - .yardopts
 - lib/jsound/convert.rb
 - lib/jsound/midi/device.rb
@@ -35,7 +36,6 @@ files:
 - lib/jsound/midi/devices/monitor.rb
 - lib/jsound/midi/devices/output_device.rb
 - lib/jsound/midi/devices/recorder.rb
-- lib/jsound/midi/devices/repeater.rb
 - lib/jsound/midi/devices/transformer.rb
 - lib/jsound/midi/message.rb
 - lib/jsound/midi/message_builder.rb
@@ -54,7 +54,6 @@ files:
 - spec/jsound/midi/devices/generator_spec.rb
 - spec/jsound/midi/devices/output_device_spec.rb
 - spec/jsound/midi/devices/recorder_spec.rb
-- spec/jsound/midi/devices/repeater_device_spec.rb
 - spec/jsound/midi/devices/transformer_spec.rb
 - spec/jsound/midi/devlice_list_spec.rb
 - spec/jsound/midi/message_builder_spec.rb
@@ -65,17 +64,18 @@ files:
 - spec/jsound/midi_spec.rb
 - spec/jsound/type_from_class_name_spec.rb
 - spec/spec_helper.rb
-- examples/harmonizer.rb
-- examples/launchpad/launchpad.rb
+- examples/harmonize.rb
+- examples/harmonize2.rb
 - examples/launchpad/launchpad_generator.rb
+- examples/launchpad/launchpad_monitor.rb
 - examples/list_devices.rb
 - examples/monitor.rb
-- examples/notes.rb
-- examples/transposer.rb
+- examples/play_notes.rb
+- examples/transpose.rb
 homepage: http://github.com/adamjmurray/jsound
-licenses: []
-
-post_install_message: 
+licenses: 
+- BSD
+post_install_message: "NOTE: this gem requires JRuby 1.5+"
 rdoc_options: []
 
 require_paths: 
@@ -92,8 +92,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version 
       version: "0"
-requirements: []
-
+requirements: 
+- JRuby 1.5+
 rubyforge_project: 
 rubygems_version: 1.8.5
 signing_key: 

data/examples/harmonizer.rb

@@ -1,25 +0,0 @@
-#!/usr/bin/env jruby
-require 'rubygems'
-require 'jsound'
-include JSound::Midi
-include Devices
-
-harmonizer = Transformer.new do |message|
-  if message.respond_to? :pitch
-    transposed = message.clone # messages are mutable, so we have to clone them to keep the original in tact
-    transposed.pitch += 3
-    [message, transposed]
-  else
-    message # pass through everything else
-  end
-end
-
-# Adjust the INPUTS and OUTPUTS as needed to use the devices you want:
-INPUTS.open_first >> harmonizer >> OUTPUTS.open_first
-# For example, to send my Akai keyboard through the harmonizer to the OS X IAC bus, I can do:
-# INPUTS.Akai >> harmonizer >> OUTPUTS.IAC
-
-# force the script to keep running (MIDI devices run in a background thread)
-while(true)
-  sleep 5
-end

data/examples/notes.rb

@@ -1,90 +0,0 @@
-#!/usr/bin/env jruby
-require 'rubygems'
-require 'jsound'
-include JSound::Midi
-
-puts "ALL DEVICES:"
-puts DEVICES
-puts
-puts "DEVICE VENDORS"
-puts DEVICES.list_all(:vendor).uniq  # list_all will include "unknown" values
-puts
-puts "INPUT DESCRIPTIONS:"
-puts INPUTS.list
-puts
-puts "OUTPUT DESCRIPTIONS:"
-puts OUTPUTS.list
-puts
-
-
-# The following examples use SimpleSynth as an output.
-# It's a free program for OS X available http://notahat.com/simplesynth
-# I assume SimpleSynth's MIDI Source is set to "SimpleSynth virtual input"
-
-# On Windows or Linux, I *think* you can just use a built-in MIDI output for your soundcard
-# If you need to do anything special on Windows/Linux, let me know @ http://github.com/adamjmurray 
-# and I'll update this example.
-
-
-#######################################################
-## FINDING INPUTS AND OUTPUTS
-##
-## Based on the input and output descriptions, 
-## you can locate the first device matching a description:
-#> OUTPUTS/'SimpleSynth'
-#
-## or just:
-#> OUTPUTS/:SimpleSynth
-#
-## the / operator is a shortcut for
-#> OUTPUTS.find /SimpleSynth/
-#
-## which has some more advanced options:
-#> OUTPUTS.find :vendor => 'M-Audio'
-#
-## Use Strings for exact matches and Regexp for partial matches
-## The find method returns the first match, find_all will return all of them: 
-#> OUTPUTS.find_all :name => /(Novation|M-Audio)/
-#
-## All of these lookup options work for the INPUTS collection too:
-#> INPUTS/'M-Audio'
-
-
-######################################################
-## ROUTING INPUTS TO OUTPUTS
-##
-## Once you have an input and an output, just connect them like so:
-#> input = INPUTS/:Akai
-#> output = OUTPUTS/:SimpleSynth
-#> input >> output
-#
-## If you are sure the inputs and outputs exist, you can do it altogether:
-#> INPUTS/:Akai >> OUTPUTS/:SimpleSynth
-
-
-######################################################
-## MONITORING INPUT
-##
-## Route to an instance of JSound::Midi::Devices::Monitor
-#> input >> Devcies::Monitor.new
-
-
-######################################################
-## GENERATING NOTES
-##
-## See message_builder.rb for list of messages currently supported,
-## including pitch_bend, control_change, channel_pressure, and more
-#
-# include JSound::Midi::Messages::Builder
-# output = OUTPUTS/:SimpleSynth
-# output.open  
-# while(true)
-#   output <= note_on(60,70)
-#   sleep 1
-#   output <= note_off(60)
-#   sleep 1
-# end
-#
-## Note that connecting to an output with >> will open the output automatically,
-## but passing in Messages with << does not.
-## That's why I explicitly call output.open in the above example.

data/examples/transposer.rb

@@ -1,20 +0,0 @@
-#!/usr/bin/env jruby
-require 'rubygems'
-require 'jsound'
-include JSound::Midi
-include Devices
-
-transposer = Transformer.new do |message|
-  message.pitch += 24 if message.respond_to? :pitch # transpose up two octaves
-  message
-end
-
-# Adjust the INPUTS and OUTPUTS as needed to use the devices you want:
-INPUTS.open_first >> transposer >> OUTPUTS.open_first
-# For example, to send my Akai keyboard through the harmonizer to the OS X IAC bus, I can do:
-# INPUTS.Akai >> transposer >> OUTPUTS.IAC
-
-# force the script to keep running (MIDI devices run in a background thread)
-while(true)
-  sleep 5
-end

data/lib/jsound/midi/devices/repeater.rb

@@ -1,28 +0,0 @@
-module JSound
-  module Midi
-    module Devices
-
-      # A device which repeats the input message to multiple outputs.
-      class Repeater < Device
-
-        # connect device(s) as the outputs for this device
-        # @param [Enumberable, Device] the device or devices to connect, or nil to disconnect the currently connected device
-        # @see {#>>}
-        def output= device
-          device = [device] if not device.is_a? Enumerable
-          super
-        end
-
-        def message(message)
-          if @output
-            for device in @output
-              device.message(message)
-            end
-          end
-        end
-
-      end
-
-    end
-  end
-end

data/spec/jsound/midi/devices/repeater_device_spec.rb

@@ -1,19 +0,0 @@
-require 'spec_helper'
-
-module JSound::Midi::Devices
-  describe Repeater do
-
-    let(:repeater) { Repeater.new }
-    let(:output1) { mock 'device1' }
-    let(:output2) { mock 'device1' }
-
-    before { repeater >> [output1, output2] }
-
-    it "should pass all messages to its outputs" do
-      output1.should_receive(:message).once.with :the_message
-      output2.should_receive(:message).once.with :the_message
-      repeater.message :the_message
-    end
-
-  end
-end