midi-communications 0.6.1 → 0.7.0

data/README.md

@@ -1,5 +1,8 @@
 # MIDI Communications
 
+[![Ruby Version](https://img.shields.io/badge/ruby-2.7+-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-LGPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
+
 **Platform independent realtime MIDI input and output for Ruby.**
 
 This library is part of a suite of Ruby libraries for MIDI:
@@ -50,7 +53,7 @@ Otherwise...
 
 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)
+* [Selecting a device](http://github.com/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)
@@ -67,18 +70,17 @@ See below for additional notes on testing with JRuby.
 
 ### Documentation
 
-[rdoc](http://rdoc.info/gems/midi-communications) (**TODO**)
+[rdoc](http://rdoc.info/gems/midi-communications)
 
 ### 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.
+* Not tested. Could have some problems.
 
 ##### Linux
 
-* (**TO CONFIRM**) *libasound* and *libasound-dev* packages are required
+* Not tested. Could have some problems.
 
 ## Differences between [MIDI Communications](https://github.com/javier-sy/midi-communications) library and [UniMIDI](https://github.com/arirusso/unimidi) library
 
@@ -89,8 +91,6 @@ See below for additional notes on testing with JRuby.
 * 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?
 
@@ -124,16 +124,6 @@ I've decided to publish my own renamed versions of the modified dependencies bec
 
 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)
@@ -144,6 +134,6 @@ Thanks to [Ari Russo](http://github.com/arirusso) for his ruby library [unimidi]
 
 ### License
 
-[MIDI Communications](https://github.com/javier-sy/midi-communications) Copyright (c) 2021-2023 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License
+[MIDI Communications](https://github.com/javier-sy/midi-communications) Copyright (c) 2021-2025 [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/examples/select_a_device.rb

@@ -35,17 +35,16 @@ output = MIDICommunications::Output.use(0)
 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
-
+# Note: first and last open the device automatically
 output = MIDICommunications::Output.first
+
+# If you want to get a device without opening it, use at/[] or all
 output = MIDICommunications::Output[0]
+output = MIDICommunications::Output.at(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
@@ -54,4 +53,4 @@ 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)
+output = MIDICommunications::Output.find { |device| device.name.match(/Launchpad/) }.open

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

@@ -2,17 +2,25 @@ require 'midi-jruby'
 
 module MIDICommunications
   module Adapter
-    # Load underlying devices using the midi-jruby gem
+    # JRuby adapter using the midi-jruby gem.
+    #
+    # Uses Java MIDI API to communicate with MIDI devices on JRuby.
+    #
+    # @api private
     module JRuby
+      # Loader for JRuby MIDI devices.
+      # @api private
       module Loader
         extend self
 
-        # @return [Array<JRuby::Input>]
+        # Returns all available MIDI input devices.
+        # @return [Array<MIDIJRuby::Input>]
         def inputs
           ::MIDIJRuby::Device.all_by_type[:input]
         end
 
-        # @return [Array<JRuby::Output>]
+        # Returns all available MIDI output devices.
+        # @return [Array<MIDIJRuby::Output>]
         def outputs
           ::MIDIJRuby::Device.all_by_type[:output]
         end

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

@@ -2,17 +2,25 @@ require 'alsa-rawmidi'
 
 module MIDICommunications
   module Adapter
-    # Load underlying devices using the alsa-rawmidi gem
+    # Linux adapter using the alsa-rawmidi gem.
+    #
+    # Uses ALSA to communicate with MIDI devices on Linux.
+    #
+    # @api private
     module Linux
+      # Loader for Linux MIDI devices.
+      # @api private
       module Loader
         extend self
 
-        # @return [Array<Linux::Input>]
+        # Returns all available MIDI input devices.
+        # @return [Array<AlsaRawMIDI::Input>]
         def inputs
           ::AlsaRawMIDI::Device.all_by_type[:input]
         end
 
-        # @return [Array<Linux::Output>]
+        # Returns all available MIDI output devices.
+        # @return [Array<AlsaRawMIDI::Output>]
         def outputs
           ::AlsaRawMIDI::Device.all_by_type[:output]
         end

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

@@ -1,18 +1,28 @@
 require 'midi-communications-macos'
 
 module MIDICommunications
+  # Platform-specific adapters for MIDI communication.
+  # @api private
   module Adapter
-    # Load underlying devices using the coremidi gem
+    # macOS adapter using the midi-communications-macos gem.
+    #
+    # Uses Core MIDI to communicate with MIDI devices on macOS.
+    #
+    # @api private
     module MacOS
+      # Loader for macOS MIDI devices.
+      # @api private
       module Loader
         extend self
 
-        # @return [Array<MacOS::Source>]
+        # Returns all available MIDI input sources.
+        # @return [Array<MIDICommunicationsMacOS::Source>]
         def inputs
           ::MIDICommunicationsMacOS::Endpoint.all_by_type[:source]
         end
 
-        # @return [Array<MacOS::Destination>]
+        # Returns all available MIDI output destinations.
+        # @return [Array<MIDICommunicationsMacOS::Destination>]
         def outputs
           ::MIDICommunicationsMacOS::Endpoint.all_by_type[:destination]
         end

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

@@ -2,18 +2,25 @@ require 'midi-winmm'
 
 module MIDICommunications
   module Adapter
-    # Load underlying devices using the midi-winmm gem
+    # Windows adapter using the midi-winmm gem.
+    #
+    # Uses Windows Multimedia API to communicate with MIDI devices.
+    #
+    # @api private
     module Windows
+      # Loader for Windows MIDI devices.
+      # @api private
       module Loader
-
         extend self
 
-        # @return [Array<Windows::Input>]
+        # Returns all available MIDI input devices.
+        # @return [Array<MIDIWinMM::Input>]
         def inputs
           ::MIDIWinMM::Device.all_by_type[:input]
         end
 
-        # @return [Array<Windows::Output>]
+        # Returns all available MIDI output devices.
+        # @return [Array<MIDIWinMM::Output>]
         def outputs
           ::MIDIWinMM::Device.all_by_type[:output]
         end

data/lib/midi-communications/device.rb

@@ -1,17 +1,40 @@
 module MIDICommunications
-  # Common logic that is shared by both Input and Output devices
+  # Common logic shared by both {Input} and {Output} devices.
+  #
+  # This module provides the core device management functionality including
+  # device discovery, selection, and lifecycle management.
+  #
+  # @api private
   module Device
-    # Methods that are shared by both Input and Output classes
+    # Class methods shared by both {Input} and {Output} classes.
+    #
+    # Provides device discovery and selection methods including enumeration,
+    # listing, searching by name, and interactive selection.
+    #
+    # @api public
     module ClassMethods
       include Enumerable
 
-      # Iterate over all devices of this direction (eg Input, Output)
+      # Iterates over all devices of this type.
+      #
+      # @yield [device] each device
+      # @yieldparam device [Input, Output] a MIDI device
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   MIDICommunications::Output.each { |o| puts o.name }
       def each(&block)
         all.each(&block)
       end
 
-      # Prints ids and names of each device to the console
-      # @return [Array<String>]
+      # Prints the ID and name of each device to the console.
+      #
+      # @return [Array<String>] array of formatted device names
+      #
+      # @example
+      #   MIDICommunications::Output.list
+      #   # 0) IAC Driver Bus 1
+      #   # 1) USB MIDI Device
       def list
         all.map do |device|
           name = "#{device.id}) #{device.display_name}"
@@ -20,15 +43,31 @@ module MIDICommunications
         end
       end
 
-      # Shortcut to select a device by its name
-      # @param [String, Symbol] name
-      # @return [Input, Output]
+      # Finds a device by its name.
+      #
+      # @param name [String, Symbol] the device name to search for
+      # @return [Input, Output, nil] the matching device or nil if not found
+      #
+      # @example
+      #   output = MIDICommunications::Output.find_by_name("IAC Driver Bus 1")
       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
+      # Interactive console prompt for device selection.
+      #
+      # Displays available devices and waits for user input. When a valid
+      # selection is received, the device is opened and returned.
+      #
+      # @yield [device] optional block to execute with the opened device
+      # @yieldparam device [Input, Output] the selected device
+      # @return [Input, Output] the selected and opened device
+      #
+      # @example
+      #   output = MIDICommunications::Output.gets
+      #   # Select a MIDI output...
+      #   # 0) IAC Driver Bus 1
+      #   # > 0
       def gets(&block)
         device = nil
         direction = get_direction
@@ -47,21 +86,39 @@ module MIDICommunications
         device
       end
 
-      # Select the first device and enable it
-      # @return [Input, Output]
+      # Selects and opens the first available device.
+      #
+      # @yield [device] optional block to execute with the device
+      # @yieldparam device [Input, Output] the device
+      # @return [Input, Output] the first device, opened
+      #
+      # @example
+      #   output = MIDICommunications::Output.first
       def first(&block)
         use_device(all.first, &block)
       end
 
-      # Select the last device and enable it
-      # @return [Input, Output]
+      # Selects and opens the last available device.
+      #
+      # @yield [device] optional block to execute with the device
+      # @yieldparam device [Input, Output] the device
+      # @return [Input, Output] the last device, opened
+      #
+      # @example
+      #   output = MIDICommunications::Output.last
       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]
+      # Selects and opens the device at the given index.
+      #
+      # @param index [Integer, Symbol] device index or :first/:last
+      # @yield [device] optional block to execute with the device
+      # @yieldparam device [Input, Output] the device
+      # @return [Input, Output] the selected device, opened
+      #
+      # @example
+      #   output = MIDICommunications::Output.use(0)
       def use(index, &block)
         index = case index
                 when :first then 0
@@ -72,9 +129,14 @@ module MIDICommunications
       end
       alias open use
 
-      # Select the device at the given index
-      # @param [Integer] index
-      # @return [Input, Output]
+      # Returns the device at the given index without opening it.
+      #
+      # @param index [Integer] device index
+      # @return [Input, Output] the device at the given index
+      #
+      # @example
+      #   device = MIDICommunications::Output.at(0)
+      #   device.open if device
       def at(index)
         all[index]
       end
@@ -101,9 +163,17 @@ module MIDICommunications
       end
     end
 
-    # Methods that are shared by both Input and Output instances
+    # Instance methods shared by both {Input} and {Output} instances.
+    #
+    # Provides device lifecycle management (open, close) and access
+    # to device attributes (name, id, manufacturer, etc.).
+    #
+    # @api public
     module InstanceMethods
-      # @param [AlsaRawMIDI::Input, AlsaRawMIDI::Output, MIDICommunicationsMacOS::Destination, MIDICommunicationsMacOS::Source, MIDIJRuby::Input, MIDIJRuby::Output, MIDIWinMM::Input, MIDIWinMM::Output] device
+      # Creates a new device wrapper.
+      #
+      # @param device [Object] platform-specific device object
+      # @api private
       def initialize(device)
         @device = device
         @enabled = false
@@ -111,11 +181,24 @@ module MIDICommunications
         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
+      # Opens the device for use.
+      #
+      # When a block is given, the device is automatically closed when
+      # the block exits. Otherwise, the device is closed at program exit.
+      #
+      # @param args [Object] arguments passed to the underlying device
+      # @yield [device] optional block to execute with the open device
+      # @yieldparam device [Input, Output] self
       # @return [Input, Output] self
+      #
+      # @example Open and close automatically with block
+      #   output.open do |o|
+      #     o.puts(0x90, 60, 100)
+      #   end  # device closed here
+      #
+      # @example Open manually (closed at program exit)
+      #   output.open
+      #   output.puts(0x90, 60, 100)
       def open(*args)
         unless @enabled
           @device.open(*args)
@@ -135,10 +218,13 @@ module MIDICommunications
         self
       end
 
-      # Close the device
-      # Params are passed to the underlying device object
-      # @param [*Object] args
-      # @return [Boolean]
+      # Closes the device.
+      #
+      # @param args [Object] arguments passed to the underlying device
+      # @return [Boolean] true if the device was closed, false if already closed
+      #
+      # @example
+      #   output.close
       def close(*args)
         if @enabled
           @device.close(*args)
@@ -149,14 +235,41 @@ module MIDICommunications
         end
       end
 
-      # Returns true if the device is not enabled
-      # @return [Boolean]
+      # Returns true if the device is closed (not enabled).
+      #
+      # @return [Boolean] true if device is closed
       def closed?
         !@enabled
       end
 
-      # Add attributes for the device instance
-      # :direction, :id, :name
+      # @!attribute [r] direction
+      #   @return [Symbol] the device direction (:input or :output)
+
+      # @!attribute [r] enabled
+      #   @return [Boolean] whether the device is currently open
+
+      # @!attribute [r] id
+      #   @return [Integer] the device ID
+
+      # @!attribute [r] manufacturer
+      #   @return [String] the device manufacturer name
+
+      # @!attribute [r] model
+      #   @return [String] the device model name
+
+      # @!attribute [r] name
+      #   @return [String] the device name
+
+      # @!attribute [r] display_name
+      #   @return [String] the device display name
+
+      # @!method enabled?
+      #   @return [Boolean] alias for {#enabled}
+
+      # @!method type
+      #   @return [Symbol] alias for {#direction}
+
+      # @api private
       def self.included(base)
         base.send(:attr_reader, :direction)
         base.send(:attr_reader, :enabled)

data/lib/midi-communications/input/stream_reader.rb

@@ -1,42 +1,48 @@
 module MIDICommunications
   class Input
+    # Methods for reading MIDI messages from an input device.
+    #
+    # Provides multiple methods for retrieving MIDI data in different formats:
+    # numeric bytes, hex strings, or raw data arrays.
+    #
+    # @api public
     module StreamReader
-      # Returns any data in the input buffer that have been received since the last call to a
-      # StreamReader method. If a StreamReader method has not yet been called, all data received
-      # since the program was initialized will be returned
+      # Reads MIDI messages from the input buffer.
       #
-      # The data is returned as array of MIDI event hashes as such:
-      #   [
-      #     { data: [144, 60, 100], timestamp: 1024 },
-      #     { data: [128, 60, 100], timestamp: 1100 },
-      #     { data: [144, 40, 120], timestamp: 1200 }
-      #   ]
+      # Returns all messages received since the last read. Each message
+      # includes the MIDI data and a timestamp.
       #
-      # In this case, the data is an array of Numeric bytes
-      # The timestamp is the number of millis since this input was enabled
-      # Arguments are passed to the underlying device object
+      # @param args [Object] arguments passed to the underlying device
+      # @return [Array<Hash>] array of message hashes with :data and :timestamp keys
       #
-      # @param [*Object] args
-      # @return [Array<Hash>]
+      # @example
+      #   messages = input.gets
+      #   # => [{ data: [144, 60, 100], timestamp: 1024 },
+      #   #     { data: [128, 60, 100], timestamp: 1100 }]
+      #
+      # @example Process messages in a loop
+      #   loop do
+      #     messages = input.gets
+      #     messages.each { |m| puts m[:data].inspect }
+      #     sleep(0.01)
+      #   end
       def gets(*args)
         @device.gets(*args)
       rescue SystemExit, Interrupt
         exit
       end
 
-      # Returns any data in the input buffer that have been received since the last call to a
-      # StreamReader method. If a StreamReader method has not yet been called, all data received
-      # since the program was initialized will be returned
+      # Reads MIDI messages as hex strings.
+      #
+      # Similar to {#gets} but returns data as hex strings instead of byte arrays.
       #
-      # Similar to Input#gets except that the returned message data as string of hex digits eg:
-      #   [
-      #     { data: "904060", timestamp: 904 },
-      #     { data: "804060", timestamp: 1150 },
-      #     { data: "90447F", timestamp: 1300 }
-      #   ]
+      # @param args [Object] arguments passed to the underlying device
+      # @return [Array<Hash>] array of message hashes with :data (String) and :timestamp keys
       #
-      # @param [*Object] args
-      # @return [Array<Hash>]
+      # @example
+      #   messages = input.gets_s
+      #   # => [{ data: "904060", timestamp: 904 },
+      #   #     { data: "804060", timestamp: 1150 }]
       def gets_s(*args)
         @device.gets_s(*args)
       rescue SystemExit, Interrupt
@@ -45,29 +51,33 @@ module MIDICommunications
       alias gets_bytestr gets_s
       alias gets_hex gets_s
 
-      # Returns any data in the input buffer that have been received since the last call to a
-      # StreamReader method. If a StreamReader method has not yet been called, all data received
-      # since the program was initialized will be returned
+      # Reads MIDI data as a flat array of bytes.
       #
-      # Similar to Input#gets except that the returned message data as an array of data bytes such as
-      #   [144, 60, 100, 128, 60, 100, 144, 40, 120]
+      # Returns all message data concatenated into a single array,
+      # without timestamps.
       #
-      # @param [*Object] args
-      # @return [Array<Integer>]
+      # @param args [Object] arguments passed to the underlying device
+      # @return [Array<Integer>] flat array of all MIDI bytes
+      #
+      # @example
+      #   data = input.gets_data
+      #   # => [144, 60, 100, 128, 60, 100, 144, 40, 120]
       def gets_data(*args)
         arr = gets(*args)
         arr.map { |msg| msg[:data] }.inject(:+)
       end
 
-      # Returns any data in the input buffer that have been received since the last call to a
-      # StreamReader method. If a StreamReader method has not yet been called, all data received
-      # since the program was initialized will be returned
+      # Reads MIDI data as a concatenated hex string.
+      #
+      # Returns all message data concatenated into a single hex string,
+      # without timestamps.
       #
-      # Similar to Input#gets except that the returned message data as a string of data such as
-      #   "90406080406090447F"
+      # @param args [Object] arguments passed to the underlying device
+      # @return [String] concatenated hex string of all MIDI data
       #
-      # @param [*Object] args
-      # @return [String]
+      # @example
+      #   data = input.gets_data_s
+      #   # => "90406080406090447F"
       def gets_data_s(*args)
         arr = gets_bytestr(*args)
         arr.map { |msg| msg[:data] }.join

data/lib/midi-communications/input.rb

@@ -1,14 +1,43 @@
 require 'midi-communications/input/stream_reader'
 
 module MIDICommunications
-  # A MIDI input device
+  # A MIDI input device for receiving MIDI messages.
+  #
+  # Input devices receive MIDI data from external controllers, instruments,
+  # or other MIDI sources. Use the class methods to discover and select
+  # available input devices.
+  #
+  # @example List available inputs
+  #   MIDICommunications::Input.list
+  #
+  # @example Open the first input and read messages
+  #   input = MIDICommunications::Input.first
+  #   messages = input.gets
+  #   # => [{ data: [144, 60, 100], timestamp: 1024 }]
+  #
+  # @example Interactive selection
+  #   input = MIDICommunications::Input.gets
+  #
+  # @example Find by name
+  #   input = MIDICommunications::Input.find_by_name("USB MIDI Device")
+  #   input.open
+  #
+  # @see Output For sending MIDI messages
+  # @see StreamReader For reading methods (gets, gets_s, etc.)
+  #
+  # @api public
   class Input
     extend Device::ClassMethods
     include Device::InstanceMethods
     include StreamReader
 
-    # All MIDI input devices -- used to populate the class
-    # @return [Array<Input>]
+    # Returns all available MIDI input devices.
+    #
+    # @return [Array<Input>] array of input devices
+    #
+    # @example
+    #   inputs = MIDICommunications::Input.all
+    #   inputs.each { |i| puts i.name }
     def self.all
       Loader.devices(direction: :input)
     end