midi-communications 0.6.1 → 0.7.1

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

data/lib/midi-communications/loader.rb

@@ -1,28 +1,104 @@
 module MIDICommunications
-
-  # Populate UniMIDI devices using the underlying device objects from the platform-specific gems
+  # Populates MIDI devices from the platform adapter.
+  #
+  # The device list is built once and kept, because enumerating is not free —
+  # on macOS it walks every device, entity and endpoint Core MIDI knows about —
+  # and most programs ask for it far more often than the machine's hardware
+  # changes. {refresh} is how a program that outlives a hardware change asks
+  # for the list again.
+  #
+  # ## What refreshing does not do
+  #
+  # A device that is still present comes back as the object it came back as
+  # before, rather than as a new wrapper around the same port. That matters
+  # because callers hold on to these: `Musa::Clock::InputMidiClock` keeps an
+  # {Input} for the length of a piece, `Musa::MIDIVoices` keeps an {Output}, and
+  # {Device::InstanceMethods#open} registers an `at_exit` on the instance.
+  # Replacing the list wholesale would leave those objects open, still due to be
+  # closed at exit, and no longer in {Input.all} — a device the program is
+  # actively using that the program can no longer find.
+  #
+  # "Still present" means the same id reporting the same name.
+  #
+  # @api private
   class Loader
     class << self
-      # Use the given platform-specific adapter to load devices
-      # @param [MIDICommunications::Adapter::Loader] loader
+      # Sets the platform-specific loader to use.
+      #
+      # Any devices already enumerated are discarded: they came from a
+      # different platform adapter and mean nothing to this one.
+      #
+      # @param loader [Module] a loader answering `inputs` and `outputs`, and
+      #   optionally `refresh`; see {PhysicalLayer}
+      # @return [Module] the loader
       def use(loader)
         @loader = loader
+        @devices = nil
+
+        loader
+      end
+
+      # Returns all MIDI devices, optionally filtered by direction.
+      #
+      # Enumerates on the first call, and then answers from what it found.
+      #
+      # @param direction [Symbol, nil] `:input` or `:output`, or nil for both
+      # @param refresh [Boolean] ask the platform adapter again first
+      # @return [Array<Input>, Array<Output>] the devices
+      def devices(direction: nil, refresh: false)
+        populate if refresh || @devices.nil?
+
+        direction.nil? ? @devices.values.flatten : @devices[direction]
+      end
+
+      # Asks the platform adapter what devices exist now.
+      #
+      # Call this when devices may have been plugged in or unplugged since the
+      # program started. Devices that are still there keep their identity; see
+      # the note on the class.
+      #
+      # @return [Array<Input, Output>] every device, after re-enumerating
+      #
+      # @example
+      #   MIDICommunications::Loader.refresh
+      #   MIDICommunications::Output.all   # now includes what was just plugged in
+      def refresh
+        devices(refresh: true)
+      end
+
+      private
+
+      # Asks the adapter for its devices and wraps them, keeping the wrapper of
+      # every device that was already there.
+      #
+      # The adapter is told to re-enumerate first if it can. Without that, an
+      # adapter with a cache of its own — the macOS one has — would hand back
+      # the same list it handed back before, and refreshing here would rebuild
+      # wrappers around a stale answer.
+      #
+      # Not on the first enumeration, though: there is nothing to invalidate
+      # yet, and asking a platform to walk its devices twice to answer the
+      # first question would make every program pay for a capability most of
+      # them never use.
+      #
+      # @return [void]
+      def populate
+        @loader.refresh if @devices && @loader.respond_to?(:refresh)
+
+        @devices = {
+          input: wrap(:input, @loader.inputs) { |device| Input.new(device) },
+          output: wrap(:output, @loader.outputs) { |device| Output.new(device) }
+        }
       end
 
-      # Get all MIDI devices
-      # @param [Hash] options
-      # @option options [Symbol] :direction Return only a particular direction of device eg :input, :output
+      # @param direction [Symbol] `:input` or `:output`
+      # @param devices [Array] the adapter's device objects
+      # @yield [device] builds a wrapper for a device not seen before
       # @return [Array<Input>, Array<Output>]
-      def devices(options = {})
-        if @devices.nil?
-          inputs = @loader.inputs.map { |device| ::MIDICommunications::Input.new(device) }
-          outputs = @loader.outputs.map { |device| ::MIDICommunications::Output.new(device) }
-          @devices = {
-            input: inputs,
-            output: outputs
-          }
-        end
-        options[:direction].nil? ? @devices.values.flatten : @devices[options[:direction]]
+      def wrap(direction, devices)
+        known = (@devices && @devices[direction] || []).to_h { |device| [[device.id, device.name], device] }
+
+        devices.map { |device| known[[device.id, device.name]] || yield(device) }
       end
     end
   end

data/lib/midi-communications/output.rb

@@ -1,27 +1,69 @@
 module MIDICommunications
-
-  # A MIDI output device
+  # A MIDI output device for sending MIDI messages.
+  #
+  # Output devices send MIDI data to external instruments, software synthesizers,
+  # or other MIDI destinations. Use the class methods to discover and select
+  # available output devices.
+  #
+  # @example List available outputs
+  #   MIDICommunications::Output.list
+  #
+  # @example Send a note to the first output
+  #   output = MIDICommunications::Output.first
+  #   output.puts(0x90, 60, 100)  # Note On, middle C, velocity 100
+  #   sleep(0.5)
+  #   output.puts(0x80, 60, 0)    # Note Off
+  #
+  # @example Send messages as hex strings
+  #   output = MIDICommunications::Output.first
+  #   output.puts_s("904060")     # Note On
+  #   output.puts_s("804060")     # Note Off
+  #
+  # @example Interactive selection
+  #   output = MIDICommunications::Output.gets
+  #
+  # @example Find by name
+  #   output = MIDICommunications::Output.find_by_name("IAC Driver Bus 1")
+  #   output.open
+  #
+  # @see Input For receiving MIDI messages
+  #
+  # @api public
   class Output
     extend Device::ClassMethods
     include Device::InstanceMethods
 
-    # All MIDI output devices -- used to populate the class
-    # @return [Array<Output>]
+    # Returns all available MIDI output devices.
+    #
+    # @return [Array<Output>] array of output devices
+    #
+    # @example
+    #   outputs = MIDICommunications::Output.all
+    #   outputs.each { |o| puts o.name }
     def self.all
       Loader.devices(direction: :output)
     end
 
-    # Sends a message to the output.
+    # Sends a MIDI message to the output.
     #
-    # The message format can be:
+    # Accepts multiple message formats for flexibility:
+    # - Numeric bytes: `output.puts(0x90, 0x40, 0x40)`
+    # - Array of numeric bytes: `output.puts([0x90, 0x40, 0x40])`
+    # - Hex string: `output.puts("904040")`
+    # - Array of strings: `output.puts(["904040", "804040"])`
+    # - Objects with `to_bytes` method: `output.puts(midi_event)`
     #
-    # 1. Numeric bytes eg output.puts(0x90, 0x40, 0x40)
-    # 2. An array of numeric bytes [0x90, 0x40, 0x40]
-    # 3. A string of bytes eg "904040"
-    # 4. An array of strings ["904040", "804040"]
+    # @param messages [Array<Integer>, Array<String>, Integer, String] MIDI messages in any supported format
+    # @return [Array<Integer>, Array<String>] the messages sent
     #
-    # @param [*Array<Integer>, *Array<String>, *Integer, *String] messages
-    # @return [Array<Integer>, Array<String>]
+    # @example Send Note On as bytes
+    #   output.puts(0x90, 60, 100)
+    #
+    # @example Send Note On as array
+    #   output.puts([0x90, 60, 100])
+    #
+    # @example Send Note On as hex string
+    #   output.puts("903C64")
     def puts(*messages)
       message = messages.first
       case message
@@ -37,10 +79,17 @@ module MIDICommunications
       end
     end
 
-    # Sends a message to the output in a form of a string eg "904040".  This method does not do
-    # type checking
-    # @param [*String] messages
-    # @return [Array<String>, Array<Array<String>>]
+    # Sends a MIDI message as a hex string.
+    #
+    # This is a lower-level method that does not perform type checking.
+    # Use {#puts} for automatic format detection.
+    #
+    # @param messages [String] one or more hex strings (e.g., "904040")
+    # @return [String, Array<String>] the message(s) sent
+    #
+    # @example
+    #   output.puts_s("904060")  # Note On
+    #   output.puts_s("804060")  # Note Off
     def puts_s(*messages)
       @device.puts_s(*messages)
       messages.count < 2 ? messages[0] : messages
@@ -48,10 +97,16 @@ module MIDICommunications
     alias puts_bytestr puts_s
     alias puts_hex puts_s
 
-    # Sends a message to the output in a form of bytes eg output.puts_bytes(0x90, 0x40, 0x40).
-    # This method does not do type checking.
-    # @param [*Array<Integer>] messages
-    # @return [Array<Integer>, Array<Array<Integer>>]
+    # Sends a MIDI message as numeric bytes.
+    #
+    # This is a lower-level method that does not perform type checking.
+    # Use {#puts} for automatic format detection.
+    #
+    # @param messages [Integer] numeric byte values (e.g., 0x90, 0x40, 0x40)
+    # @return [Integer, Array<Integer>] the message bytes sent
+    #
+    # @example
+    #   output.puts_bytes(0x90, 0x40, 0x40)  # Note On, note 64, velocity 64
     def puts_bytes(*messages)
       @device.puts_bytes(*messages)
       messages.count < 2 ? messages[0] : messages

data/lib/midi-communications/physical_layer.rb

@@ -0,0 +1,105 @@
+module MIDICommunications
+  # The contract a platform adapter's device objects must satisfy.
+  #
+  # This module defines no behaviour. It exists because the contract between
+  # `midi-communications` and the low-level gem underneath it was, until now,
+  # implicit: spread across {Loader}, {Device}, {Input::StreamReader} and
+  # {Output}, and discoverable only by reading all four and inferring what they
+  # assume. That is workable while one adapter exists. It stops being workable
+  # the moment a second one is written, because the second author reads the
+  # documentation rather than the macOS gem's source, and the documentation did
+  # not say any of this.
+  #
+  # An adapter supplies a loader module answering `inputs` and `outputs` with
+  # arrays of device objects, and optionally `refresh` (see {Loader.refresh}).
+  # Each device object must behave as described below. {Input} and {Output}
+  # wrap them; nothing else in this library touches them.
+  #
+  # ## Attributes, readable before the device is opened
+  #
+  # {Input} and {Output} read these in their constructor, which runs while the
+  # device list is being built and long before anyone opens anything. An
+  # adapter that only knows a device's name once it is open does not satisfy
+  # this contract.
+  #
+  # | Method | Type | Meaning |
+  # | --- | --- | --- |
+  # | `id` | Integer | identifies the device; see the note on uniqueness below |
+  # | `name` | String | the device's name |
+  # | `display_name` | String | the name to show a person choosing a device |
+  # | `manufacturer` | String, nil | **nil when the platform does not report it** |
+  # | `model` | String, nil | **nil when the platform does not report it** |
+  # | `type` | Symbol | `:input`/`:source`, or `:output`/`:destination` |
+  #
+  # `manufacturer` and `model` are nullable on purpose. Core MIDI reports both
+  # as strings; the Windows Multimedia API reports numeric codes from a
+  # registry that stopped being maintained in the 1990s, from which no honest
+  # string can be derived. An adapter in that position returns nil rather than
+  # an empty string or an invention, so that a consumer filtering on either can
+  # tell the difference between "does not match" and "not known here".
+  #
+  # ### On the uniqueness of `name`
+  #
+  # `name` is a label, not an identifier. Two devices may report the same one,
+  # and a consumer matching on it may therefore be matching the wrong device.
+  #
+  # This is measured, not defensive. The Windows Multimedia API stores 31
+  # characters of a name and drops the rest without saying so, and two endpoints
+  # whose names differed only past that point came back identical in every field
+  # it reports — same name, same manufacturer code, same product code, same
+  # driver version — distinguishable only by their index. Two ports of one
+  # interface whose long names differ at the end collapse the same way.
+  #
+  # {Device::ClassMethods#find_by_name} returns the first match, which is all it
+  # can do.
+  #
+  # ### On the uniqueness of `id`
+  #
+  # `id` is unique **within a direction**. It is not necessarily unique across
+  # both: on Windows a device is identified by its index among inputs or among
+  # outputs, so input 0 and output 0 are different devices and both are valid.
+  # Core MIDI happens to number endpoints of both directions from a single
+  # counter, but that is a property of Core MIDI and not something a consumer
+  # may rely on. Nothing in this library compares an id across directions —
+  # `Input.all` and `Output.all` each search their own list.
+  #
+  # ## Lifecycle
+  #
+  # - `open(*args)` — makes the device usable. Opening an already-open device
+  #   must succeed and do nothing, because {Device::InstanceMethods#open} may be
+  #   called on a device a caller already holds open.
+  # - `close(*args)` — releases it. Closing an already-closed device must
+  #   succeed.
+  #
+  # ## Input
+  #
+  # - `gets` — **blocks** until at least one message has arrived, then returns
+  #   every message accumulated, as an Array of Hashes with:
+  #   - `:data`, an Array of Integer bytes making up **one complete message**,
+  #     System Exclusive included, already split per message;
+  #   - `:timestamp`, a Float of seconds — when the library received the
+  #     message, not a stamp applied by the driver. Both existing adapters take
+  #     it with `Time.now.to_f` at the moment the message reaches Ruby.
+  # - `gets_s` — the same, with `:data` as a hex String.
+  #
+  # The blocking is the part most easily got wrong, and it is load-bearing.
+  # `Musa::Clock::InputMidiClock` reads MIDI Clock in a loop with no delay of
+  # its own, relying on `gets` to be where the thread waits. An adapter whose
+  # `gets` returned an empty array immediately would turn that loop into a spin
+  # on a full core — and would do it silently, because the music would still
+  # play.
+  #
+  # ## Output
+  #
+  # - `puts_bytes(*bytes)` — sends one message given as Integer bytes.
+  # - `puts_s(hex_string)` — sends one message given as hex.
+  #
+  # Both must accept System Exclusive.
+  #
+  # @see Loader how adapters are registered and their devices enumerated
+  # @see Input::StreamReader the reading methods built on `gets`
+  #
+  # @api public
+  module PhysicalLayer
+  end
+end

data/lib/midi-communications/platform.rb

@@ -1,10 +1,19 @@
 module MIDICommunications
-
-  # Deal with different dependencies between different user environments
+  # Handles platform detection and adapter loading.
+  #
+  # Automatically detects the current platform (macOS, Linux, Windows, JRuby)
+  # and loads the appropriate low-level MIDI adapter.
+  #
+  # @api private
   module Platform
     extend self
 
-    # Loads the proper MIDI library and adapter for the user's environment
+    # Loads the correct MIDI adapter for the current platform.
+    #
+    # Called automatically when the library is required. Detects the
+    # platform and loads the corresponding adapter gem.
+    #
+    # @return [void]
     def bootstrap
       require("midi-communications/adapter/#{platform_lib}")
       Loader.use(platform_module::Loader)

data/lib/midi-communications/type_conversion.rb

@@ -1,14 +1,29 @@
 module MIDICommunications
-
-  # Utility for converting between different data formats
+  # Utility methods for converting between MIDI data formats.
+  #
+  # @api public
   module TypeConversion
     extend self
 
-    # Convert an array of numeric bytes to string of hex bytes
-    # @param [Array<Integer>] bytes An array of numeric bytes eg [0x90, 0x40, 0x40]
-    # @return [String] A string of hex bytes eg "904040"
+    # Converts an array of numeric bytes to a hex string.
+    #
+    # Every byte becomes exactly two characters. Without the padding a byte
+    # below 0x10 produces one, and the string can no longer be read back as
+    # bytes: [0x90, 0x0A, 0x64] came out as "90a64", which is five characters
+    # and describes no MIDI message at all.
+    #
+    # @param bytes [Array<Integer>] array of numeric bytes (e.g., [0x90, 0x40, 0x40])
+    # @return [String] hex string representation (e.g., "904040")
+    #
+    # @example
+    #   TypeConversion.numeric_byte_array_to_hex_string([0x90, 0x40, 0x40])
+    #   # => "904040"
+    #
+    # @example A byte below 0x10 still takes two characters
+    #   TypeConversion.numeric_byte_array_to_hex_string([0x90, 0x0A, 0x64])
+    #   # => "900A64"
     def numeric_byte_array_to_hex_string(bytes)
-      bytes.map { |b| b.to_s(16) }.join
+      bytes.map { |byte| format('%02X', byte) }.join
     end
   end
 end

data/lib/midi-communications/version.rb

@@ -1,3 +1,4 @@
 module MIDICommunications
-  VERSION = '0.6.1'.freeze
+  # Current version of the midi-communications gem.
+  VERSION = '0.7.1'.freeze
 end

data/lib/midi-communications.rb

@@ -8,6 +8,7 @@
 
 # modules
 require 'midi-communications/device'
+require 'midi-communications/physical_layer'
 require 'midi-communications/platform'
 require 'midi-communications/type_conversion'
 
@@ -18,6 +19,44 @@ require 'midi-communications/output'
 
 require_relative 'midi-communications/version'
 
+# Platform-independent realtime MIDI input and output for Ruby.
+#
+# MIDICommunications provides a unified API for MIDI communication across
+# different platforms (macOS, Linux, Windows, JRuby). It automatically
+# detects the current platform and loads the appropriate low-level adapter.
+#
+# This library is part of the MusaDSL MIDI suite:
+# - {https://github.com/javier-sy/midi-events MIDI Events} - MIDI message representation
+# - {https://github.com/javier-sy/midi-parser MIDI Parser} - MIDI data parsing
+# - {https://github.com/javier-sy/midi-communications MIDI Communications} - MIDI I/O (this library)
+# - {https://github.com/javier-sy/midi-communications-macos MIDI Communications MacOS} - macOS adapter
+#
+# @example List all MIDI outputs
+#   MIDICommunications::Output.list
+#   # 0) IAC Driver Bus 1
+#   # 1) USB MIDI Device
+#
+# @example Send a note to the first output
+#   output = MIDICommunications::Output.first
+#   output.puts(0x90, 60, 100)  # Note On, middle C, velocity 100
+#   sleep(0.5)
+#   output.puts(0x80, 60, 0)    # Note Off
+#
+# @example Receive MIDI from an input
+#   input = MIDICommunications::Input.first
+#   loop do
+#     messages = input.gets
+#     messages.each { |m| puts m.inspect }
+#   end
+#
+# @example Interactive device selection
+#   output = MIDICommunications::Output.gets  # Prompts user to select
+#   input = MIDICommunications::Input.gets
+#
+# @see Input MIDI input device class
+# @see Output MIDI output device class
+#
+# @api public
 module MIDICommunications
   Platform.bootstrap
 end

data/midi-communications.gemspec

@@ -3,31 +3,39 @@ require_relative 'lib/midi-communications/version'
 Gem::Specification.new do |s|
   s.name        = 'midi-communications'
   s.version     = MIDICommunications::VERSION
-  s.date        = '2025-08-23'
+  s.date        = '2026-09-06'
   s.summary     = 'Platform independent realtime MIDI input and output for Ruby'
   s.description = 'Access MIDI devices for MacOS, Linux (wip), Windows (wip) and JRuby (wip).'
   s.authors     = ['Javier Sánchez Yeste']
   s.email       = ['javier.sy@gmail.com']
   s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  s.homepage    = 'https://rubygems.org/gems/midi-communications'
+  s.homepage    = 'https://github.com/javier-sy/midi-communications'
   s.license     = 'LGPL-3.0-or-later'
 
   s.required_ruby_version = '>= 2.7'
 
-  # TODO
-  #s.metadata    = {
-  # "source_code_uri" => "https://",
-  # "homepage_uri" => "",
-  # "documentation_uri" => "",
-  # "changelog_uri" => ""
-  #}
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/midi-communications'
+  }
 
-  s.add_runtime_dependency 'midi-communications-macos', '~> 0.6'
+  # RubyGems has no platform-conditional dependencies, so both platform layers
+  # are declared unconditionally. That is harmless only because both are pure
+  # Ruby over a library the operating system already provides -- CoreMIDI and
+  # winmm.dll -- so each installs anywhere and is simply not required where it
+  # does not apply. A layer that shipped compiled binaries per platform could
+  # not be declared this way.
+  s.add_runtime_dependency 'midi-communications-macos', '~> 0.7'
+  s.add_runtime_dependency 'midi-communications-windows', '~> 0.0.1'
   # s.add_runtime_dependency  'alsa-rawmidi', '~> 0.3', '>= 0.3.1'
   # s.add_runtime_dependency  'midi-jruby', '~> 0.1', '>= 0.1.4'
-  # s.add_runtime_dependency  'midi-winmm', '~> 0.1', '>= 0.1.10'
 
   s.add_development_dependency 'minitest', '~>5', '>= 5.14.4'
   s.add_development_dependency 'rake', '~>13', '>= 13.0.6'
   s.add_development_dependency 'shoulda-context', '~>2', '>= 2.0.0'
+
+  s.add_development_dependency 'yard', '~> 0.9'
+  s.add_development_dependency 'redcarpet', '~> 3.6'
+  s.add_development_dependency 'webrick', '~> 1.8'
 end