jsound 0.1.0-java

data/examples/transposer.rb

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

@@ -0,0 +1,4 @@
+require 'java'
+require 'jsound/convert'
+require 'jsound/type_from_class_name'
+require 'jsound/midi'

data/lib/jsound/convert.rb

@@ -0,0 +1,30 @@
+module JSound
+
+  # Helper methods for converting MIDI data values
+  module Convert
+
+    # The maximum value for unsigned 14-bit integer
+    MAX_14BIT_VALUE = 16383  # == 127 + (127 << 7) 
+
+    # Convert a single integer to a [least_significant, most_significant] pair of 7-bit ints
+    def to_7bit(value)
+      [value & 127, (value >> 7) & 127]
+    end
+
+    # Convert a [least_significant, most_significant] pair of 7-bit ints to a single integer     
+    def from_7bit(lsb, msb)
+      lsb + (msb << 7)
+    end
+
+    # Scales a float from the range [-1.0, 1.0] to the integer range [0, 16383]
+    def normalized_float_to_14bit(float)
+      (MAX_14BIT_VALUE*(float+1)/2).round
+    end
+
+    # Make all methods be module functions (accessible by sending the method name to module directly)
+    instance_methods.each do |method|
+      module_function method
+    end
+
+  end
+end

data/lib/jsound/midi.rb

@@ -0,0 +1,77 @@
+require 'jsound/midi/message'
+require 'jsound/midi/messages/channel_pressure'
+require 'jsound/midi/messages/control_change'
+require 'jsound/midi/messages/note_on'
+require 'jsound/midi/messages/note_off'
+require 'jsound/midi/messages/pitch_bend'
+require 'jsound/midi/messages/poly_pressure'
+require 'jsound/midi/messages/program_change'
+
+require 'jsound/midi/message_builder'
+
+require 'jsound/midi/device'
+require 'jsound/midi/devices/generator'
+require 'jsound/midi/devices/jdevice'
+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'
+
+
+module JSound
+
+  # Module containing all MIDI functionality.
+  #
+  # Also provies the core interface for accessing MIDI devices, see the device list constants defined here.
+  #
+  module Midi
+    include_package 'javax.sound.midi'
+
+    # All MIDI devices
+    # @return [DeviceList]
+    DEVICES = DeviceList.new
+
+    # MIDI input devices
+    # @return [DeviceList] a list of {Devices::InputDevice}s
+    INPUTS = DeviceList.new
+
+    # MIDI output devices
+    # @return [DeviceList] a list of {Devices::OutputDevice}s
+    OUTPUTS = DeviceList.new
+
+    # MIDI synthesizer devices
+    # @return [DeviceList]
+    SYNTHESIZERS = SYNTHS = DeviceList.new
+
+    # MIDI sequencer devices
+    # @return [DeviceList]
+    SEQUENCERS = DeviceList.new
+
+    # Refresh the list of connected devices.
+    # @note this happens automatically when JSound is required.
+    def refresh_devices
+      [DEVICES,INPUTS,OUTPUTS,SYNTHESIZERS,SEQUENCERS].each{|collection| collection.clear}
+      MidiSystem.getMidiDeviceInfo.each do |device_info| 
+        java_device = MidiSystem.getMidiDevice(device_info)
+        device = Devices::JDevice.from_java(java_device)
+        case device.type
+        when :sequencer   then SEQUENCERS   << device
+        when :synthesizer then SYNTHESIZERS << device
+        when :input       then INPUTS       << device
+        when :output      then OUTPUTS      << device
+        end 
+        DEVICES << device    
+      end
+      DEVICES
+    end    
+    module_function :refresh_devices
+
+    # Refresh devices automatically when loaded:
+    refresh_devices()  
+
+  end
+end

data/lib/jsound/midi/device.rb

@@ -0,0 +1,72 @@
+module JSound
+  module Midi
+
+    # 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
+
+      # 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}
+      # @see DeviceList#open
+      def open
+      end
+
+      # return true if this device is currently open
+      def open?
+        # typically, ruby devices are always open, subclasses might not be
+        true
+      end
+
+      # Close the device and free up any resources used by this device.
+      # @note this operation is typically only relevant for Java-based devices such as {Devices::InputDevice} and {Devices::OutputDevice}
+      def close
+      end
+
+      def type
+        # The base Device behaves like a 'pass through'
+        @type ||= (self.class == Device ? :pass_through : self.class.type)
+      end
+
+      # the device connected to this device's output
+      # @return [Device] the connected device, or nil if nothing is connected
+      def output
+        @output
+      end
+
+      # connect a device as the output for this device
+      # @param [Device] the device to connect, or nil to disconnect the currently connected device
+      # @see {#>>}
+      def output= device
+        @output = device
+      end
+
+      # Connect a device as the output for this device. shortcut for {#output=}
+      # @param [Device] the device to connect, or nil to disconnect the currently connected device
+      # @see {#output=}
+      def >> device
+        self.output= device
+      end
+
+      # Send a message to this device
+      # @param [Message]
+      # @see #<=
+      def message(message)
+        # default behavior is to pass the message to any connected output
+        @output.message(message) if @output
+      end
+
+      # send a message to this device. shortcut for {#message}
+      # @see #message
+      def <=(message)
+        message(message)
+      end
+
+      def to_s
+        "MIDI #{type} device"
+      end
+
+    end
+
+  end
+end

data/lib/jsound/midi/device_list.rb

@@ -0,0 +1,157 @@
+module JSound
+  module Midi
+
+    # A collection of MIDI {Device}s that provides various methods to lookup (and optionally auto-open) specific devices
+    #
+    # @see Midi the Midi module for constants to access your system devices
+    #
+    class DeviceList
+
+      # The devices within this collection.
+      attr_reader :devices
+
+      def initialize(list=[])
+        @devices = list
+      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
+      # @return [Device] the first matching {Device} or nil if nothing matched
+      # @note I/O devices need to be opened before they can be used (see {Device#open})
+      # @see #find_all
+      # @see #open
+      # @example {OUTPUTS}.find "IAC Driver Bus 1"  #=> find the first output with the exact description "IAC Driver Bus 1"
+      # @example {OUTPUTS}.find /IAC/  #=> find the first output with a description containing "IAC"
+      # @example {OUTPUTS}.find :vendor => "Apple Inc."  #=> find the first output with the exact vendor field "Apple Inc."
+      # @example {OUTPUTS}.find :vendor => /Apple /  #=> find the first output with a vendor field containing "Apple"
+      #
+      def find(criteria)
+        search :find, criteria
+      end
+
+      # Find all {Device}s 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
+      # @return [Array] an Array of all matching {Device}s or [] if nothing matched
+      # @note I/O devices need to be opened before they can be used (see {Device#open})
+      # @see #find for examples
+      # @see #open
+      #
+      def find_all(criteria)
+        search :find_all, criteria
+      end
+
+      # Acts like Array#[] for Numeric and Range arguments. Otherwise acts like {#find_all}.
+      #
+      # @see #find_all
+      #
+      def [](criteria)
+        if criteria.kind_of? Fixnum or criteria.kind_of? Range
+          @devices[criteria]
+        else
+          find_all(criteria)
+        end
+      end
+
+      # Find the first device matching the argument and open it.
+      #
+      # @param device matches description against for a Regexp argument, matches the device field against the value for a Hash argument, otherwise checks for an equal description
+      # @return [Device] the device
+      # @raise an error if no device can be found
+      # @see #find
+      # @see #find_all
+      #
+      def open(device)
+        device = find device unless device.is_a? Device
+        if device
+          device.open
+        else
+          raise "Device note found: #{device}"
+        end
+        device
+      end
+
+      # Find and open the first device with a description matching the argument.
+      #
+      # @return [Device] the device
+      # @raise an error if no device can be found
+      # @see #open
+      #
+      def /(regexp)
+        regexp = Regexp.new(regexp.to_s, Regexp::IGNORECASE) if not regexp.kind_of? Regexp
+        open regexp
+      end
+
+      # open the first device in this list
+      #
+      # @return [Device] the device
+      # @raise an error if no device can be found
+      # @see #open
+      #
+      def open_first
+        open @devices.first
+      end
+
+      # open and return the last device in this list
+      #
+      # @return [Device] the device
+      # @raise an error if no device can be found
+      # @see #open
+      #
+      def open_last
+        open @devices.first
+      end
+
+      def to_s
+        @devices.join("\n")
+      end
+
+      ########################
+      private
+
+      def search(iterator, criteria)
+        field, target_value = field_and_target_value_for(criteria)
+        matcher = matcher_for(target_value)
+        @devices.send(iterator) do |device|
+          device.send(field).send(matcher, target_value)
+        end
+      end
+
+      def field_and_target_value_for(criteria)
+        if criteria.is_a? Hash
+          first_key = criteria.keys.first
+          return first_key, criteria[first_key]
+        else
+          return :description, criteria
+        end
+      end
+
+      def matcher_for(target_value)
+        case target_value
+        when Regexp then '=~'
+        else '=='
+        end
+      end
+
+      # Pass method calls through to the underlying Array.
+      # If Array doesn't understand the method, call {#open} with a case-insensitive regexp match
+      # against description, treating underscore as a wildcard.
+      #
+      # @example # {INPUTS}.Akai => open the first "Akai" input device connected to this computer
+      # @example # {INPUTS}.Akai_2 => open an input device matching /Akai.*2/i
+      #
+      def method_missing(sym, *args, &block)
+        if @devices.respond_to? sym
+          @devices.send(sym, *args, &block)
+        elsif args.length == 0 and block.nil?
+          self.open /#{sym.to_s.sub '_','.*'}/i
+        else
+          super
+        end
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,22 @@
+module JSound
+  module Midi
+    module Devices
+
+      # A device which provides methods for generating MIDI command messages.
+      # See JSound::Midi::Messages::Builder for the available methods.
+      class Generator < Device
+
+        # For all the methods defined in the MessageBuilder module (note_on, pitch_bend, control_change, etc),
+        # define a corresponding device method that constructs the message and sends the connected device
+        MessageBuilder.private_instance_methods.each do |method|
+          define_method(method) do |*args|
+            message = MessageBuilder.send(method, *args)
+            self.message message
+          end
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+module JSound
+  module Midi
+    module Devices
+
+      # A device that receives messages from a system MIDI input port,
+      # and passes the messages to any connected device.
+      #
+      # Available inputs are contained in the {INPUTS} list in the {Midi} module.
+      #
+      class InputDevice < JDevice
+
+        # Wrap a javax.sound.midi.MidiDevice receiver to provide MIDI output.
+        #
+        # @note Typically you won't instantiate these directly. Instead, find an input via the {INPUTS} list in the {Midi} module.
+        #
+        def initialize(java_device)
+          super(java_device, :input)
+          @bridge = Bridge.new(self)
+          java_device.transmitter.receiver = @bridge
+        end
+
+        def output=(device)
+          super
+          @bridge.output= device
+        end
+
+        # A subcomponent of {InputDevice} that implements javax.sound.midi.Receiver
+        # by translating incoming Java MIDI Messages to Ruby Messages.
+        class Bridge < Device
+          include javax.sound.midi.Receiver
+
+          def initialize(source_device)
+            @source_device = source_device
+          end
+
+          # Receives incoming Java MIDI Messages, converts them to Ruby Messages,
+          # and sends them to any connected devices.
+          def send(java_message, timestamp=-1)
+            self.message Message.from_java(java_message, :source => @source_device)
+          rescue
+            STDERR.puts $! if $DEBUG # otherwise this can get swallowed
+            raise
+          end
+
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+module JSound
+  module Midi
+    module Devices
+
+      # A Java-provided MIDI device (wraps javax.sound.midi.MidiDevice objects)
+      class JDevice < Device
+
+        # the javax.sound.midi.MidiDevice.Info object for this java device
+        attr_reader :info
+
+        # the description of this device
+        # @return [String]
+        attr_reader :description
+
+        attr_reader :type
+
+        # All open JDevices
+        # @note All open devices will be automatically closed at_exit
+        def self.open_devices
+          @@open_devices ||= []
+        end
+        at_exit do
+          # Close all open devices so we don't hang the program at shutdown time
+          for device in JDevice.open_devices
+            device.close
+          end
+        end
+
+        def initialize(java_device, type)
+          @java_device = java_device
+          @info = @java_device.deviceInfo
+          @description = @info.description
+          @type = type
+        end
+
+        def self.from_java(java_device)
+          case java_device
+          when javax.sound.midi.Sequencer then type = :sequencer
+          when javax.sound.midi.Synthesizer then type = :synthesizer
+          else
+            # This assumes a single device cannot be both an input and an output:
+            if java_device.maxTransmitters != 0
+              return InputDevice.new(java_device)
+            elsif java_device.maxReceivers != 0
+              return OutputDevice.new(java_device)
+            else
+              type = :unknown
+            end
+          end
+          new java_device, type
+        end
+
+        # @see Device#open
+        # @note All open devices will be automatically closed at_exit
+        def open
+          unless @java_device.open?
+            puts "Opening #{to_s}"
+            @java_device.open
+            self.class.open_devices << self
+          end
+        end
+
+        # @see Device#close
+        def close
+          if @java_device.open?
+            puts "Closing #{to_s}"
+            @java_device.close
+            self.class.open_devices.delete(self)
+          end
+        end
+
+        def method_missing(sym, *args, &block)
+          if @java_device.respond_to? sym
+            @java_device.send(sym, *args, &block)
+          else
+            @info.send(sym, *args, &block)
+          end
+        end
+
+        def respond_to?(sym)
+          super or @java_device.respond_to? sym or info.respond_to? sym
+        end
+
+        def [](field)
+          send field
+        end
+
+        def to_s
+          "#{super}: #{info.description}"
+        end
+
+        def inspect
+          to_s
+        end
+
+      end
+
+    end
+  end
+end