midi-communications 0.5.1

data/LICENSE.unimidi

@@ -0,0 +1,13 @@
+Copyright 2010-2017 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,149 @@
+# MIDI Communications
+
+**Platform independent realtime MIDI input and output for Ruby.**
+
+This library is part of a suite of Ruby libraries for MIDI:
+
+| Function | Library |
+| --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) |
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) |
+| Low level MIDI interface to Linux | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [alsa-rawmidi](http://github.com/arirusso/alsa-rawmidi)) | 
+| Low level MIDI interface to JRuby | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [midi-jruby](http://github.com/arirusso/midi-jruby))| 
+| Low level MIDI interface to Windows | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [midi-winm](http://github.com/arirusso/midi-winmm)) | 
+
+This library is based on [Ari Russo's](http://github.com/arirusso) library [UniMIDI](https://github.com/arirusso/unimidi).
+
+### Features
+
+* Supports OSX, Linux, JRuby, Windows and Cygwin
+* No compilation required
+* Both input and output to and from multiple devices concurrently
+* Generalized handling of different MIDI and SysEx Message types
+* On OSX use IAC to internally route MIDI to other programs
+* No events history and no buffers optimization
+
+### Requirements
+
+**MIDI Communications** uses one of the following libraries, depending on which platform you're using it on.  The necessary library should install automatically with the midi-communications gem.
+
+Platform
+
+* OSX: [midi-communications-macos](http://github.com/javier-sy/midi-communications-macos)
+* JRuby: [midi-jruby](http://github.com/arirusso/midi-jruby) (**TODO: update to midi-communications-jruby**)
+* Linux: [alsa-rawmidi](http://github.com/arirusso/alsa-rawmidi) (**TODO: update to midi-communications-linux**)
+* Windows/Cygwin: [midi-winmm](http://github.com/arirusso/midi-winmm) (**TODO: update to midi-communications-windows**)
+
+### Install
+
+If you're using Bundler, add this line to your application's Gemfile:
+
+`gem "midi-communications"`
+
+Otherwise...
+
+`gem install midi-communications`
+
+### Usage
+
+Some examples are included with the library:
+
+* [Selecting a device](http://github.com/arirusso/javier-sy/midi-communications/blob/master/examples/select_a_device.rb)
+* [MIDI input](http://github.com/javier-sy/midi-communications/blob/master/examples/input.rb)
+* [MIDI output](http://github.com/javier-sy/midi-communications/blob/master/examples/output.rb)
+* [MIDI Sysex output](http://github.com/javier-sy/midi-communications/blob/master/examples/sysex_output.rb)
+
+### Tests
+
+**MIDI Communications** includes a set of tests which assume that an output is connected to an input.  You will be asked to select which input and output as the test is run.
+
+The tests can be run using:
+
+`rake test`
+
+See below for additional notes on testing with JRuby.
+
+### Documentation
+
+[rdoc](http://rdoc.info/gems/midi-communications) (**TODO**)
+
+### Platform Specific Notes
+
+##### JRuby
+
+* (**TO CONFIRM**) You must be in 1.9 mode.  This is normally accomplished by passing --1.9 to JRuby at the command line.  For testing in 1.9 mode, use `jruby --1.9 -S rake test`
+* (**TO CONFIRM**) javax.sound has some documented issues with SysEx messages in some versions OSX Snow Leopard which do affect this library.
+
+##### Linux
+
+* (**TO CONFIRM**) *libasound* and *libasound-dev* packages are required
+
+## Differences between [MIDI Communications](https://github.com/javier-sy/midi-communications) library and [UniMIDI](https://github.com/arirusso/unimidi) library
+
+[MIDI Communications](https://github.com/javier-sy/midi-communications) is mostly a clone of [UniMIDI](https://github.com/arirusso/unimidi) with some modifications:
+* Uses [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) instead of [ffi-coremidi](https://github.com/arirusso/ffi-coremidi)
+* Removed buffering (to reduce CPU usage in some scenarios)
+* Source updated to Ruby 2.7 code conventions (method keyword parameters instead of options = {}, hash keys as 'key:' instead of ':key =>', etc.)
+* Updated dependencies versions
+* Renamed module to MIDICommunications instead of UniMIDI
+* Renamed gem to midi-communications instead of unimidi
+* TODO: update tests to use rspec instead of rake
+* TODO: migrate to (or confirm it's working ok on) Ruby 3.0 and Ruby 3.1
+
+## Then, why does exist this library if it is mostly a clone of another library?
+
+The author has been developing since 2016 a Ruby project called
+[Musa DSL](https://github.com/javier-sy/musa-dsl) that needs a way
+of representing MIDI Events and a way of communicating with
+MIDI Instruments and MIDI Control Surfaces.
+
+[Ari Russo](https://github.com/arirusso) has done a great job creating
+several interdependent Ruby libraries that allow
+MIDI Events representation ([MIDI Message](https://github.com/arirusso/midi-message)
+and [Nibbler](https://github.com/arirusso/nibbler))
+and communication with MIDI Instruments and MIDI Control Surfaces
+([unimidi](https://github.com/arirusso/unimidi),
+[ffi-coremidi](https://github.com/arirusso/ffi-coremidi) and others)
+that, **with some modifications**, I've been using in MusaDSL.
+
+After thinking about the best approach to publish MusaDSL
+I've decided to publish my own renamed versions of the modified dependencies because:
+
+* The original libraries have features
+  (buffering, very detailed logging and processing history information, not locking behaviour when waiting input midi messages)
+  that are not needed in MusaDSL and, in fact,
+  can degrade the performance on some use cases in MusaDSL.
+* The requirements for **Musa DSL** users probably will evolve in time, so it will be easier to maintain an independent source code base.
+* Some differences on the approach of the modifications vs the original library doesn't allow to merge the modifications on the original libraries.
+* Then the renaming of the libraries is needed to avoid confusing existent users of the original libraries.
+* Due to some of the interdependencies of Ari Russo libraries,
+  the modification and renaming on some of the low level libraries (ffi-coremidi, etc.)
+  forces to modify and rename unimidi library.
+
+All in all I have decided to publish a suite of libraries optimized for MusaDSL use case that also can be used by other people in their projects.
+
+| Function | Library | Based on Ari Russo's| Difference |
+| --- | --- | --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) | [MIDI Message](https://github.com/arirusso/midi-message) | removed parsing, small improvements |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) | [Nibbler](https://github.com/arirusso/nibbler) | removed process history information, minor optimizations |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) | [unimidi](https://github.com/arirusso/unimidi) | use of [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos, removed process history information, removed buffering, removed command line script)
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) | [ffi-coremidi](https://github.com/arirusso/ffi-coremidi) | removed buffering and process history information, locking behaviour when waiting midi events, improved midi devices name detection, minor optimizations |
+| Low level MIDI interface to Linux | **TO DO** | | |
+| Low level MIDI interface to JRuby | **TO DO** | | |
+| Low level MIDI interface to Windows | **TO DO** | | |
+
+## Author
+
+* [Javier Sánchez Yeste](https://github.com/javier-sy)
+
+## Acknowledgements
+
+Thanks to [Ari Russo](http://github.com/arirusso) for his ruby library [unimidi](https://github.com/arirusso/unimidi) licensed under Apache License 2.0.
+
+### License
+
+[MIDI Communications](https://github.com/javier-sy/midi-communications) Copyright (c) 2021 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License
+
+[unimidi](https://github.com/arirusso/unimidi) Copyright (c) 2010-2017 [Ari Russo](http://arirusso.com), licensed under Apache License 2.0 (see the file LICENSE.unimidi)

data/Rakefile

@@ -0,0 +1,44 @@
+$LOAD_PATH.prepend __dir__
+$LOAD_PATH.prepend File.join(__dir__, 'lib')
+
+require 'rake'
+require 'rake/testtask'
+require 'midi-communications'
+
+namespace(:test) do
+  task all: [:unit, :integration]
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/integration/**/*_test.rb']
+    t.verbose = true
+  end
+
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/unit/**/*_test.rb']
+    t.verbose = true
+  end
+end
+
+Rake::Task['test'].enhance ['test:all']
+
+platforms = ['generic', 'x86_64-darwin10.7.0', 'i386-mingw32', 'java', 'i686-linux']
+
+task(:build) do
+  require 'midi-communications-gemspec'
+  platforms.each do |platform|
+    MIDICommunications::Gemspec.new(platform)
+    filename = "midi-communications-#{platform}.gemspec"
+    system "gem build #{filename}"
+    system "rm #{filename}"
+  end
+end
+
+task(release: :build) do
+  platforms.each do |platform|
+    system "gem push midi-communications-#{MIDICommunications::VERSION}-#{platform}.gem"
+  end
+end
+
+task(default: [:test])

data/examples/input.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.prepend(File.expand_path('../lib', __dir__))
+
+require 'midi-communications'
+
+# Prompts the user to select a midi input
+# Sends an inspection of the first 10 messages messages that input receives to standard out
+
+num_messages = 10
+
+# Prompt the user
+input = MIDICommunications::Input.gets
+
+# using their selection...
+
+puts 'send some MIDI to your input now...'
+
+num_messages.times do
+  m = input.gets
+  puts(m)
+end
+
+puts 'finished'

data/examples/output.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.prepend(File.expand_path('../lib', __dir__))
+
+require 'midi-communications'
+
+# Prompts the user to select a midi output
+# Sends some arpeggiated chords to the output
+
+notes = [36, 40, 43] # C E G
+octaves = 5
+duration = 0.1
+
+# Prompt the user to select an output
+output = MIDICommunications::Output.gets
+
+# using their selection...
+(0..((octaves-1)*12)).step(12) do |oct|
+  notes.each do |note|
+    output.puts(0x90, note + oct, 100) # note on
+    sleep(duration) # wait
+    output.puts(0x80, note + oct, 100) # note off
+  end
+end

data/examples/select_a_device.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.prepend(File.expand_path('../lib', __dir__))
+
+require 'midi-communications'
+
+#
+# This is an example that explains how to select an output.
+# It's not really meant to be run.
+#
+
+# Prompt the user for selection in the console
+
+output = MIDICommunications::Output.gets
+
+# The user will see a list that reflects their local MIDI configuration, and be prompted to select a number
+
+# Select a MIDI output
+# 1) IAC Device
+# 2) Roland UM-2 (1)
+# 3) Roland UM-2 (2)
+# >
+
+# Once they've selected, the device that corresponds with their selection is returned.
+
+# (Note that it's returned open so you don't need to call output.open)
+
+# Hard-code the selection like this
+
+output = MIDICommunications::Output.use(:first)
+output = MIDICommunications::Output.use(0)
+
+# or
+
+output = MIDICommunications::Output.open(:first)
+output = MIDICommunications::Output.open(0)
+
+# If you want to wait to open the device, you can select it with any of these "finder" methods
+
+output = MIDICommunications::Output.first
+output = MIDICommunications::Output[0]
+output = MIDICommunications::Output.all[0]
+output = MIDICommunications::Output.all.first
+output = MIDICommunications::Device.all_by_type(:output)[0]
+output = MIDICommunications::Device.all_by_type(:output).first
+
+# You'll need to call open on these before you use it or an exception will be raised
+
+output.open
+
+# It's also possible to select a device by name
+
+output = MIDICommunications::Output.find_by_name('Roland UM-2 (1)').open
+
+# or using regex match
+
+output = MIDICommunications::Output.find { |device| device.name.match(/Launchpad/) }.open(:first)

data/examples/sysex_output.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.prepend(File.expand_path('../lib', __dir__))
+
+require 'midi-communications'
+
+# Prompts the user to select a MIDI output
+# Sends a MIDI system exclusive message to that output
+ 
+sysex_msg = [0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7]
+
+output = MIDICommunications::Output.gets
+
+output.puts(sysex_msg)

data/lib/midi-communications/adapter/jruby.rb

@@ -0,0 +1,22 @@
+require 'midi-jruby'
+
+module MIDICommunications
+  module Adapter
+    # Load underlying devices using the midi-jruby gem
+    module JRuby
+      module Loader
+        extend self
+
+        # @return [Array<JRuby::Input>]
+        def inputs
+          ::MIDIJRuby::Device.all_by_type[:input]
+        end
+
+        # @return [Array<JRuby::Output>]
+        def outputs
+          ::MIDIJRuby::Device.all_by_type[:output]
+        end
+      end
+    end
+  end
+end

data/lib/midi-communications/adapter/linux.rb

@@ -0,0 +1,22 @@
+require 'alsa-rawmidi'
+
+module MIDICommunications
+  module Adapter
+    # Load underlying devices using the alsa-rawmidi gem
+    module Linux
+      module Loader
+        extend self
+
+        # @return [Array<Linux::Input>]
+        def inputs
+          ::AlsaRawMIDI::Device.all_by_type[:input]
+        end
+
+        # @return [Array<Linux::Output>]
+        def outputs
+          ::AlsaRawMIDI::Device.all_by_type[:output]
+        end
+      end
+    end
+  end
+end

data/lib/midi-communications/adapter/macos.rb

@@ -0,0 +1,22 @@
+require 'midi-communications-macos'
+
+module MIDICommunications
+  module Adapter
+    # Load underlying devices using the coremidi gem
+    module MacOS
+      module Loader
+        extend self
+
+        # @return [Array<MacOS::Source>]
+        def inputs
+          ::MIDICommunicationsMacOS::Endpoint.all_by_type[:source]
+        end
+
+        # @return [Array<MacOS::Destination>]
+        def outputs
+          ::MIDICommunicationsMacOS::Endpoint.all_by_type[:destination]
+        end
+      end
+    end
+  end
+end

data/lib/midi-communications/adapter/windows.rb

@@ -0,0 +1,23 @@
+require 'midi-winmm'
+
+module MIDICommunications
+  module Adapter
+    # Load underlying devices using the midi-winmm gem
+    module Windows
+      module Loader
+
+        extend self
+
+        # @return [Array<Windows::Input>]
+        def inputs
+          ::MIDIWinMM::Device.all_by_type[:input]
+        end
+
+        # @return [Array<Windows::Output>]
+        def outputs
+          ::MIDIWinMM::Device.all_by_type[:output]
+        end
+      end
+    end
+  end
+end

data/lib/midi-communications/device.rb

@@ -0,0 +1,195 @@
+module MIDICommunications
+  # Common logic that is shared by both Input and Output devices
+  module Device
+    # Methods that are shared by both Input and Output classes
+    module ClassMethods
+      include Enumerable
+
+      # Iterate over all devices of this direction (eg Input, Output)
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Prints ids and names of each device to the console
+      # @return [Array<String>]
+      def list
+        all.map do |device|
+          name = "#{device.id}) #{device.display_name}"
+          puts(name)
+          name
+        end
+      end
+
+      # Shortcut to select a device by its name
+      # @param [String, Symbol] name
+      # @return [Input, Output]
+      def find_by_name(name)
+        all.find { |device| name.to_s == device.name }
+      end
+
+      # Streamlined console prompt that asks the user to select a device
+      # When their input is received, the device is selected and enabled
+      def gets(&block)
+        device = nil
+        direction = get_direction
+        puts ''
+        puts "Select a MIDI #{direction}..."
+        while device.nil?
+          list
+          print '> '
+          selection = $stdin.gets.chomp
+          if selection != ''
+            selection = Integer(selection) rescue nil
+            device = all.find { |d| d.id == selection } unless selection.nil?
+          end
+        end
+        device.open(&block)
+        device
+      end
+
+      # Select the first device and enable it
+      # @return [Input, Output]
+      def first(&block)
+        use_device(all.first, &block)
+      end
+
+      # Select the last device and enable it
+      # @return [Input, Output]
+      def last(&block)
+        use_device(all.last, &block)
+      end
+
+      # Select the device at the given index and enable it
+      # @param [Integer] index
+      # @return [Input, Output]
+      def use(index, &block)
+        index = case index
+                when :first then 0
+                when :last then all.count - 1
+                else index
+                end
+        use_device(at(index), &block)
+      end
+      alias open use
+
+      # Select the device at the given index
+      # @param [Integer] index
+      # @return [Input, Output]
+      def at(index)
+        all[index]
+      end
+      alias [] at
+
+      private
+
+      # The direction of the device eg "input", "output"
+      # @return [String]
+      def get_direction
+        name.split('::').last.downcase
+      end
+
+      # Enable the given device
+      # @param [Input, Output] device
+      # @return [Input, Output]
+      def use_device(device, &block)
+        if device.enabled?
+          yield(device) if block_given?
+        else
+          device.open(&block)
+        end
+        device
+      end
+    end
+
+    # Methods that are shared by both Input and Output instances
+    module InstanceMethods
+      # @param [AlsaRawMIDI::Input, AlsaRawMIDI::Output, MIDICommunicationsMacOS::Destination, MIDICommunicationsMacOS::Source, MIDIJRuby::Input, MIDIJRuby::Output, MIDIWinMM::Input, MIDIWinMM::Output] device
+      def initialize(device)
+        @device = device
+        @enabled = false
+
+        populate_from_device
+      end
+
+      # Enable the device for use
+      # Params are passed to the underlying device object
+      # Can be passed a block to which the device will be passed in as the yieldparam
+      # @param [*Object] args
+      # @return [Input, Output] self
+      def open(*args)
+        unless @enabled
+          @device.open(*args)
+          @enabled = true
+        end
+        if block_given?
+          begin
+            yield(self)
+          ensure
+            close
+          end
+        else
+          at_exit do
+            close
+          end
+        end
+        self
+      end
+
+      # Close the device
+      # Params are passed to the underlying device object
+      # @param [*Object] args
+      # @return [Boolean]
+      def close(*args)
+        if @enabled
+          @device.close(*args)
+          @enabled = false
+          true
+        else
+          false
+        end
+      end
+
+      # Returns true if the device is not enabled
+      # @return [Boolean]
+      def closed?
+        !@enabled
+      end
+
+      # Add attributes for the device instance
+      # :direction, :id, :name
+      def self.included(base)
+        base.send(:attr_reader, :direction)
+        base.send(:attr_reader, :enabled)
+        base.send(:attr_reader, :id)
+        base.send(:attr_reader, :manufacturer)
+        base.send(:attr_reader, :model)
+        base.send(:attr_reader, :name)
+        base.send(:attr_reader, :display_name)
+        base.send(:alias_method, :enabled?, :enabled)
+        base.send(:alias_method, :type, :direction)
+      end
+
+      private
+
+      # Populate the direction attribute
+      def populate_direction
+        @direction = case @device.type
+                     when :source, :input then :input
+                     when :destination, :output then :output
+                     end
+      end
+
+      # Populate attributes from the underlying device object
+      def populate_from_device
+        @id = @device.id
+
+        @manufacturer = @device.manufacturer
+        @model = @device.model
+        @name = @device.name
+        @display_name = @device.display_name
+
+        populate_direction
+      end
+    end
+  end
+end