jsound 0.1.0-java

data/.yardopts

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

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2010-2011, Adam Murray (adam@compusition.com).
+
+All rights reserved.
+
+Redistribution and use of the "JSound" Ruby library, in source and binary
+forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in
+   the documentation and/or other materials provided with the
+   distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,96 @@
+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)
+
+
+
+Project Info
+------------
+
+Home:     http://github.com/adamjmurray/jsound
+
+Author:   Adam Murray (adam@compusition.com)
+
+License:  Distributed under a permissive BSD-style license, see 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
+
+
+
+Documentation
+-------------
+
+Gem: http://rubydoc.info/gems/jsound/0.0.1/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
+-----------------
+
+### Run Tests ###
+
+     rake spec
+
+and to quickly check compatibility with multiple JRuby versions via rvm:
+
+     rvm jruby-1.5.6,jruby-1.6.2 rake spec:fast
+
+
+### Generate Docs ###
+
+     yard
+     open doc/frames.html
+
+
+### Project Roadmap ###
+
+https://www.pivotaltracker.com/projects/85719

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rspec/core/rake_task'
+require 'rake/clean'
+
+task :default => :spec
+
+CLEAN.include('doc') # clean and clobber do the same thing for now
+
+
+desc "Run RSpec tests with full output"
+RSpec::Core::RakeTask.new do |spec|
+  spec.rspec_opts = ["--color", "--format", "nested"]
+end
+
+namespace :spec do
+  desc "Run RSpecs tests with summary output and fast failure"
+  RSpec::Core::RakeTask.new(:fast) do |spec|
+    spec.rspec_opts = ["--color", "--fail-fast"]
+  end
+end

data/examples/harmonizer.rb

@@ -0,0 +1,25 @@
+#!/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/launchpad/launchpad.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env jruby --debug
+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.
+
+
+# A higher-level representation of the messages coming from the Launchpad
+class LaunchpadMessage < Messages::Message
+  def initialize(button_group, position, pressed, channel=0, source=nil)
+    @type = :launchpad_button
+    @button_group = button_group
+    @position = position
+    @pressed = pressed
+    @data = {:button_group => button_group, :position => position, :pressed => pressed}
+    @channel = channel
+    @source = source
+  end
+end
+
+# A device that converts the lower-level MIDI messages into LaunchpadMessages
+class LaunchadTranslator < Devices::Device  
+  def <=(message)
+    case message.type    
+
+    when :control_change
+      button_group = :top
+      pressed = (message.value > 0)
+      position = message.control - 104       
+      
+    when :note_on
+      # everything else
+      pressed = (message.velocity > 0)
+      value = message.pitch      
+      row = value / 16
+      col = value % 16
+      if col > 7
+        button_group = :right
+        position = row
+      else
+        button_group = :grid
+        position = [col,row]
+      end  
+    end
+    
+    super LaunchpadMessage.new(button_group, position, pressed, message.channel, message.source)    
+  rescue
+    puts $!
+  end  
+end
+
+
+# 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
+
+
+# force the script to keep running (MIDI devices run in a background thread)
+while(true)
+  sleep 5
+end

data/examples/launchpad/launchpad_generator.rb

@@ -0,0 +1,111 @@
+# 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
+
+class LaunchpadGenerator < JSound::Midi::Devices::Generator
+  
+  def grid(x,y,color=3)
+    x = clip(x,0,15)
+    y = clip(y,0,7)
+    c = color_value(color)
+    note_on(16*y + x, c)
+  end
+
+  def scene_launch(position,color=3)
+    grid(8,position,color)
+  end
+
+
+  def control_row(position,color=3)
+    c = color_value(color)
+    p = 104 + clip(position,0,7)
+    control_change(p,c)
+  end
+
+  def up(     color=3); control_row(0,color) end
+  def down(   color=3); control_row(1,color) end
+  def left(   color=3); control_row(2,color) end
+  def right(  color=3); control_row(3,color) end
+  def session(color=3); control_row(4,color) end
+  def user1(  color=3); control_row(5,color) end
+  def user2(  color=3); control_row(6,color) end
+  def mixer(  color=3); control_row(7,color) end
+
+  def all_on(brightness=3)
+    # convert brightness values 0,1,2,3 to 0,125,126,127
+    # (0=off, 125=low, 126=med, 127=high)
+    b = clip(brightness,0,3)
+    b += 124 if b > 0
+    control_change(0,b)
+  end
+
+  def all_off
+    control_change(0,0)
+  end
+
+  def duty_cycle(numerator,denominator)
+    n = clip(numerator,1,16)
+    d = clip(denominator,3,18)
+    if n < 9
+      control_change(30, 16*(n-1) + (d-3))
+    else
+      control_change(31, 16*(n-9) + (d-3))
+    end
+  end
+
+  def clip(value,min,max)
+    value = min if value.nil? or value < min
+    value = max if value > max
+    return value
+  end
+
+  def color_value(color)
+    case color
+    when Array
+      g,r = color[0],color[1]
+    when Numeric
+      g,r = color,0
+    else case color.to_s
+      when 'green',  'g' then g,r = 3,0
+      when 'yellow', 'y' then g,r = 3,2
+      when 'amber',  'a' then g,r = 3,3    
+      when 'orange', 'o' then g,r = 2,3
+      when 'red',    'r' then g,r = 0,3 
+      else g,r = 0,0     
+      end
+    end
+    g = clip(g.to_i,0,3)
+    r = clip(r.to_i,0,3)
+    return 16*g + r
+  end
+  
+end

data/examples/list_devices.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env jruby
+require 'rubygems'
+require 'jsound'
+include JSound::Midi
+
+puts DEVICES

data/examples/monitor.rb

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

data/examples/notes.rb

@@ -0,0 +1,90 @@
+#!/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.