midi-communications 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c54220cd8b8985c56f5a076a8f16a1e6bacf76e6e71ed84cbf86c5e090014fad
-  data.tar.gz: d29c68b6c6a1d04aca389d3a7b093a16da815d7532194ef0020aa0215967db40
+  metadata.gz: 21b452b0402e76c284ff8e74011e54e193528f27eccc6e67e03d90be46eeaf98
+  data.tar.gz: e5bc3c0d00284f259f2808fe2e3f6b231eadea633c6cf7bf6a9217f49cdeb0d5
 SHA512:
-  metadata.gz: 8705e81b899107f807099b4ff073bedaea01bfeffeddd956a6833d7143c9cb65118b9b67f2f9a3fedf6539aea5578732478ef0f88f1bfe09d4c3257961e259ae
-  data.tar.gz: 0a41a5f60e95477efdf99be00a5af42a5cdaf3e957ddf234aadef9df8b0d518f5bd01f339476ba23b5e1a6899fae803e79684c25b13b03ed7d2a450186d975b5
+  metadata.gz: 86c68969777a5d3322ffab60927763a39b742149746165251ae51cecb6f3c718daa0f3043bd37f7386fcb60db5a787ad5a9d8df66c4ee45287ea5ab74914b22d
+  data.tar.gz: fb2441905249105c97d21f648a2fb347a702de332cde9d02013dc4b2b239341f1eee76d0b4faaa2dfdb5ee52552cf7e179e7b269feadc6c7fd7a542a60f16a47

data/.github/workflows/notify-plugin.yml

@@ -0,0 +1,17 @@
+name: Notify Plugin Rebuild
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger nota-plugin rebuild
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.PLUGIN_REBUILD_PAT }}
+          repository: javier-sy/nota-plugin
+          event-type: source-updated
+          client-payload: '{"repo": "${{ github.repository }}", "sha": "${{ github.sha }}"}'

data/README.md

@@ -15,7 +15,7 @@ This library is part of a suite of Ruby libraries for MIDI:
 | 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)) | 
+| Low level MIDI interface to Windows | [MIDI Communications Windows Layer](https://github.com/javier-sy/midi-communications-windows) |
 
 This library is based on [Ari Russo's](http://github.com/arirusso) library [UniMIDI](https://github.com/arirusso/unimidi).
 
@@ -37,7 +37,7 @@ 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**)
+* Windows: [midi-communications-windows](https://github.com/javier-sy/midi-communications-windows)
 
 ### Install
 
@@ -134,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-2025 [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-2026 [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/lib/midi-communications/adapter/macos.rb

@@ -26,6 +26,17 @@ module MIDICommunications
         def outputs
           ::MIDICommunicationsMacOS::Endpoint.all_by_type[:destination]
         end
+
+        # Discards the Core MIDI device list so that the next enumeration
+        # walks the system again.
+        #
+        # Guarded on `populated?` because Device.refresh clears a list that
+        # does not exist until something has enumerated once.
+        #
+        # @return [void]
+        def refresh
+          ::MIDICommunicationsMacOS::Device.refresh if ::MIDICommunicationsMacOS::Device.populated?
+        end
       end
     end
   end

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

@@ -1,10 +1,15 @@
-require 'midi-winmm'
+require 'midi-communications-windows'
 
 module MIDICommunications
   module Adapter
-    # Windows adapter using the midi-winmm gem.
+    # Windows adapter using the midi-communications-windows gem.
     #
-    # Uses Windows Multimedia API to communicate with MIDI devices.
+    # Uses the Windows Multimedia (WinMM) API to communicate with MIDI devices.
+    #
+    # There is no `refresh` here, unlike the macOS adapter: that gem asks WinMM
+    # afresh on every enumeration and keeps no list of its own, so there is
+    # nothing to invalidate. {Loader} only calls `refresh` on an adapter that
+    # answers to it.
     #
     # @api private
     module Windows
@@ -14,15 +19,15 @@ module MIDICommunications
         extend self
 
         # Returns all available MIDI input devices.
-        # @return [Array<MIDIWinMM::Input>]
+        # @return [Array<MIDICommunicationsWindows::Input>]
         def inputs
-          ::MIDIWinMM::Device.all_by_type[:input]
+          ::MIDICommunicationsWindows::Device.all_by_type[:input]
         end
 
         # Returns all available MIDI output devices.
-        # @return [Array<MIDIWinMM::Output>]
+        # @return [Array<MIDICommunicationsWindows::Output>]
         def outputs
-          ::MIDIWinMM::Device.all_by_type[:output]
+          ::MIDICommunicationsWindows::Device.all_by_type[:output]
         end
       end
     end

data/lib/midi-communications/device.rb

@@ -45,8 +45,12 @@ module MIDICommunications
 
       # Finds a device by its name.
       #
+      # Returns the **first** device with that name. A name is a label rather
+      # than an identifier and two devices may share one — see the note on names
+      # in {PhysicalLayer} — so where it matters, select by {#id} instead.
+      #
       # @param name [String, Symbol] the device name to search for
-      # @return [Input, Output, nil] the matching device or nil if not found
+      # @return [Input, Output, nil] the first matching device, or nil
       #
       # @example
       #   output = MIDICommunications::Output.find_by_name("IAC Driver Bus 1")

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

@@ -7,25 +7,30 @@ module MIDICommunications
     #
     # @api public
     module StreamReader
-      # Reads MIDI messages from the input buffer.
+      # Reads MIDI messages from the input.
       #
-      # Returns all messages received since the last read. Each message
-      # includes the MIDI data and a timestamp.
+      # **Blocks until at least one message has arrived**, and then returns
+      # every message that accumulated. It never returns an empty array.
+      #
+      # This is part of the contract every platform adapter implements, not an
+      # accident of one of them — see {PhysicalLayer}. A reader loop therefore
+      # needs no delay of its own, and adding one only delays the messages that
+      # are already waiting.
       #
       # @param args [Object] arguments passed to the underlying device
-      # @return [Array<Hash>] array of message hashes with :data and :timestamp keys
+      # @return [Array<Hash>] message hashes with :data and :timestamp keys
       #
       # @example
       #   messages = input.gets
       #   # => [{ data: [144, 60, 100], timestamp: 1024 },
       #   #     { data: [128, 60, 100], timestamp: 1100 }]
       #
-      # @example Process messages in a loop
+      # @example Read messages as they arrive
       #   loop do
-      #     messages = input.gets
-      #     messages.each { |m| puts m[:data].inspect }
-      #     sleep(0.01)
+      #     input.gets.each { |message| puts message[:data].inspect }
       #   end
+      #
+      # @see PhysicalLayer the contract this method's behaviour comes from
       def gets(*args)
         @device.gets(*args)
       rescue SystemExit, Interrupt
@@ -34,7 +39,8 @@ module MIDICommunications
 
       # Reads MIDI messages as hex strings.
       #
-      # Similar to {#gets} but returns data as hex strings instead of byte arrays.
+      # Blocks exactly as {#gets} does, and returns the same messages with
+      # `:data` as a hex string instead of an array of bytes.
       #
       # @param args [Object] arguments passed to the underlying device
       # @return [Array<Hash>] array of message hashes with :data (String) and :timestamp keys
@@ -53,8 +59,8 @@ module MIDICommunications
 
       # Reads MIDI data as a flat array of bytes.
       #
-      # Returns all message data concatenated into a single array,
-      # without timestamps.
+      # Blocks as {#gets} does, and returns all message data concatenated into
+      # a single array, without timestamps.
       #
       # @param args [Object] arguments passed to the underlying device
       # @return [Array<Integer>] flat array of all MIDI bytes

data/lib/midi-communications/loader.rb

@@ -1,37 +1,104 @@
 module MIDICommunications
-  # Populates MIDI devices using platform-specific adapters.
+  # Populates MIDI devices from the platform adapter.
   #
-  # This class lazily loads and caches MIDI devices from the underlying
-  # platform adapter (macOS, Linux, Windows, or JRuby).
+  # 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
       # Sets the platform-specific loader to use.
       #
-      # @param loader [Module] a loader module with `inputs` and `outputs` methods
+      # 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.
       #
-      # Lazily loads and caches devices from the platform adapter on first call.
-      #
-      # @param options [Hash] filter options
-      # @option options [Symbol] :direction Return only :input or :output devices
-      # @return [Array<Input>, Array<Output>] array of devices
-      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]]
+      # 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
+
+      # @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 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/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/type_conversion.rb

@@ -7,14 +7,23 @@ module MIDICommunications
 
     # 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,4 +1,4 @@
 module MIDICommunications
   # Current version of the midi-communications gem.
-  VERSION = '0.7.0'.freeze
+  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'
 

data/midi-communications.gemspec

@@ -3,7 +3,7 @@ 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']
@@ -20,10 +20,16 @@ Gem::Specification.new do |s|
     'documentation_uri' => 'https://www.rubydoc.info/gems/midi-communications'
   }
 
+  # 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'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: midi-communications
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Javier Sánchez Yeste
 bindir: bin
 cert_chain: []
-date: 2025-08-23 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: midi-communications-macos
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: midi-communications-windows
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -132,6 +146,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/notify-plugin.yml"
 - ".gitignore"
 - ".version"
 - ".yardopts"
@@ -154,6 +169,7 @@ files:
 - lib/midi-communications/input/stream_reader.rb
 - lib/midi-communications/loader.rb
 - lib/midi-communications/output.rb
+- lib/midi-communications/physical_layer.rb
 - lib/midi-communications/platform.rb
 - lib/midi-communications/type_conversion.rb
 - lib/midi-communications/version.rb