midi-communications-windows 0.0.3

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

@@ -0,0 +1,206 @@
+module MIDICommunicationsWindows
+  # A MIDI output port: somewhere to send messages.
+  #
+  # @example Send a note through the first output
+  #   output = MIDICommunicationsWindows::Output.first
+  #   output.open
+  #   output.puts(0x90, 60, 100)   # Note On, middle C
+  #   sleep 0.5
+  #   output.puts(0x80, 60, 0)     # Note Off
+  #
+  # @example Send the same thing as a hex string
+  #   output.puts_s('903C64')
+  #
+  # @see Input for receiving
+  #
+  # @api public
+  class Output
+    extend Device::ClassMethods
+    include Device::InstanceMethods
+
+    # @return [Symbol] `:output`
+    def self.direction
+      :output
+    end
+
+    # Sends a MIDI message, in whichever form it is given.
+    #
+    # @param args [Array<Integer>, Array<String>, Integer, String] one message,
+    #   as loose bytes, an array of bytes, or a hex string
+    # @return [Boolean] true
+    # @raise [Error] if WinMM refuses the message
+    #
+    # @example Every one of these sends the same Note On
+    #   output.puts(0x90, 60, 100)
+    #   output.puts([0x90, 60, 100])
+    #   output.puts('903C64')
+    def puts(*args)
+      case args.first
+      when Array then args.each { |argument| puts(*argument) }
+      when Integer then puts_bytes(*args)
+      when String then puts_s(*args)
+      end
+
+      true
+    end
+    alias write puts
+
+    # Sends a MIDI message given as a hex string.
+    #
+    # @param data [String] hex, two characters per byte, e.g. `'903C64'`
+    # @return [Boolean] true
+    # @raise [Error] if WinMM refuses the message
+    def puts_s(data)
+      puts_bytes(*data.scan(/../).map(&:hex))
+    end
+    alias puts_bytestr puts_s
+    alias puts_hex puts_s
+
+    # Sends a MIDI message given as numeric bytes.
+    #
+    # System Exclusive takes a different route through WinMM than everything
+    # else, and this is where the two part company.
+    #
+    # @param data [Array<Integer>] the message, status byte first
+    # @return [Boolean] true
+    # @raise [Error] if WinMM refuses the message
+    def puts_bytes(*data)
+      Message.sysex?(data) ? send_sysex(data) : send_short(data)
+
+      true
+    end
+
+    private
+
+    # Opens the port.
+    #
+    # `CALLBACK_NULL` asks WinMM for no notifications at all. The only event an
+    # output can raise is `MM_MOM_DONE`, saying a System Exclusive buffer has
+    # finished, and {#send_sysex} learns that from the buffer's own flags
+    # instead. Asking for no callback keeps the driver from ever calling into
+    # Ruby, which is one whole class of threading problem that then cannot
+    # occur on the sending side.
+    #
+    # @return [void]
+    # @raise [Error]
+    # @api private
+    def connect
+      handle_pointer = FFI::MemoryPointer.new(:uintptr_t)
+
+      API.check!(API.midiOutOpen(handle_pointer, @id, 0, 0, API::CALLBACK_NULL),
+                 :midiOutOpen, :output)
+
+      @handle = handle_pointer.read(:uintptr_t)
+    end
+
+    # Closes the port.
+    #
+    # `midiOutReset` first, and not only for tidiness: it turns off every note
+    # the port has left sounding and releases any buffer still queued. Closing
+    # without it can leave a synthesiser holding notes with nothing left to
+    # send it a Note Off.
+    #
+    # @return [void]
+    # @raise [Error]
+    # @api private
+    def disconnect
+      API.check!(API.midiOutReset(@handle), :midiOutReset, :output)
+      API.check!(API.midiOutClose(@handle), :midiOutClose, :output)
+
+      @handle = nil
+    end
+
+    # Sends a message of three bytes or fewer.
+    #
+    # @param data [Array<Integer>]
+    # @return [void]
+    # @raise [Error]
+    # @api private
+    def send_short(data)
+      API.check!(API.midiOutShortMsg(@handle, Message.pack(data)), :midiOutShortMsg, :output)
+    end
+
+    # Sends a System Exclusive message.
+    #
+    # WinMM wants such a message in a buffer it has been told about, and the
+    # sequence is fixed: prepare the header, send it, wait for the driver to
+    # finish with it, then unprepare. Unpreparing early fails with
+    # `MIDIERR_STILLPLAYING`, and freeing the buffer early is worse than that.
+    #
+    # The wait can be a real one. MIDI runs at 31250 baud, so on a physical
+    # interface a byte takes about 320 microseconds and a 200-byte dump should
+    # occupy something like 64 milliseconds during which this method does not
+    # return — a caller sending System Exclusive from a sequencer thread should
+    # know that is possible. Said as arithmetic rather than as measurement: the
+    # only device this has been run against is a software synthesiser, which
+    # marks the buffer done at once because there is no wire, and returned in
+    # well under a millisecond.
+    #
+    # @param data [Array<Integer>] the whole message, 0xF0 through 0xF7
+    # @return [void]
+    # @raise [Error]
+    # @api private
+    def send_sysex(data)
+      buffer = FFI::MemoryPointer.new(:uint8, data.size)
+      buffer.write_array_of_uint8(data)
+
+      header = API::MIDIHdr.new
+      header[:lpData] = buffer
+      header[:dwBufferLength] = data.size
+      header[:dwBytesRecorded] = data.size
+
+      API.check!(API.midiOutPrepareHeader(@handle, header, API::MIDIHdr.size),
+                 :midiOutPrepareHeader, :output)
+
+      begin
+        API.check!(API.midiOutLongMsg(@handle, header, API::MIDIHdr.size), :midiOutLongMsg, :output)
+        wait_until_sent(header)
+      rescue Error
+        # The driver still owns the buffer. Unpreparing it now would fail with
+        # MIDIERR_STILLPLAYING and the memory would be freed underneath a device
+        # that is still reading it; midiOutReset takes it back first.
+        API.midiOutReset(@handle)
+        raise
+      ensure
+        API.midiOutUnprepareHeader(@handle, header, API::MIDIHdr.size)
+      end
+    end
+
+    # Blocks until the driver marks the buffer done, or gives up.
+    #
+    # There is no blocking WinMM call to wait on, so this polls the flag the
+    # driver sets. The interval is short enough not to add meaningfully to a
+    # transfer measured in tens of milliseconds, and long enough not to spin.
+    #
+    # The wait is bounded because the flag is set by a device that can go away:
+    # unplug an interface in the middle of a dump and it is never set at all.
+    # Without a limit this would spin for the life of the process, on whichever
+    # thread happened to be sending — in MusaDSL, the sequencer's.
+    #
+    # @param header [API::MIDIHdr]
+    # @return [void]
+    # @raise [Error] if the device has not finished within {SYSEX_TIMEOUT}
+    # @api private
+    def wait_until_sent(header)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + SYSEX_TIMEOUT
+
+      until (header[:dwFlags] & API::MHDR_DONE) != 0
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          raise Error.new(:midiOutLongMsg, nil,
+                          "the device did not finish sending a #{header[:dwBufferLength]}-byte " \
+                          "System Exclusive message within #{SYSEX_TIMEOUT} s")
+        end
+
+        sleep SYSEX_POLL_INTERVAL
+      end
+    end
+
+    # How often to look at a System Exclusive buffer's done flag, in seconds.
+    SYSEX_POLL_INTERVAL = 0.001
+
+    # How long to wait for a System Exclusive message to go out, in seconds.
+    # MIDI runs at 31250 baud, so this is room for roughly 3 kB — far more than
+    # any message, and short enough that a vanished device is noticed.
+    SYSEX_TIMEOUT = 1.0
+  end
+end

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

@@ -0,0 +1,20 @@
+module MIDICommunicationsWindows
+  # Utility methods for converting between MIDI data formats.
+  #
+  # @api public
+  module TypeConversion
+    extend self
+
+    # Converts an array of numeric bytes to a hex string.
+    #
+    # @param bytes [Array<Integer>] numeric bytes, e.g. `[0x90, 0x40, 0x40]`
+    # @return [String] uppercase hex, two characters per byte, e.g. `'904040'`
+    #
+    # @example
+    #   TypeConversion.numeric_bytes_to_hex_string([0x90, 0x40, 0x40])
+    #   # => "904040"
+    def numeric_bytes_to_hex_string(bytes)
+      bytes.map { |byte| format('%02X', byte) }.join
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+module MIDICommunicationsWindows
+  # Current version of the midi-communications-windows gem.
+  VERSION = '0.0.3'.freeze
+end

data/lib/midi-communications-windows.rb

@@ -0,0 +1,76 @@
+#
+# midi-communications-windows
+# Realtime MIDI IO with Ruby for Windows
+#
+# (c)2026 Javier Sánchez Yeste, licensed under LGPL 3.0 License
+#
+
+# Libs
+require 'ffi'
+
+# Modules with no platform binding of their own, so that they load anywhere
+require 'midi-communications-windows/message'
+require 'midi-communications-windows/type_conversion'
+
+# Modules and classes that bind winmm.dll
+require 'midi-communications-windows/api'
+require 'midi-communications-windows/device'
+require 'midi-communications-windows/input'
+require 'midi-communications-windows/output'
+
+require_relative 'midi-communications-windows/version'
+
+# Windows-specific MIDI I/O through the Windows Multimedia (WinMM) API.
+#
+# This library gives low-level access to MIDI ports on Windows by binding
+# `winmm.dll` with FFI. It is normally used through the higher-level
+# {https://github.com/javier-sy/midi-communications midi-communications} gem,
+# which selects it automatically on Windows.
+#
+# The classes are {Input}, for receiving, and {Output}, for sending. {Device}
+# enumerates both.
+#
+# ## Why WinMM, and not one of the newer APIs
+#
+# Windows has three MIDI APIs a program could use. WinMM is the oldest, and as
+# of February 2026 it is also the most sensible choice for Ruby.
+#
+# Windows MIDI Services, generally available in Windows 11 since then, replaced
+# the MIDI stack underneath. The existing MIDI 1.0 APIs were reconnected to the
+# new service rather than retired, so a WinMM client reaches what the new stack
+# offers with nothing installed — including the loopback endpoints the system
+# now creates itself, which used to need a third-party driver.
+#
+# Whether a port can be opened by more than one program at a time follows the
+# endpoint, not the API. Measured: two clients shared a loopback input and both
+# received every message, while a second open of a classic `wdmaud` device was
+# refused as already in use. On Windows 10 there is no Windows MIDI Services.
+#
+# The new App SDK offers MIDI 2.0 and UMP, which this library does not need —
+# `midi-communications` and MusaDSL are MIDI 1.0 throughout — and it is
+# published only as WinRT. Microsoft's own guidance is that other languages
+# need a WinRT projection from their toolchain, and Ruby has none.
+#
+# ## Why no compiled artifact
+#
+# `winmm.dll` is present on every Windows installation, so this gem binds a
+# library that is already there and ships no binary of its own. The only
+# compiled dependency is `ffi` itself, which is published for every Windows
+# platform including ARM64. Distributing platform-specific binaries through
+# RubyGems is where installations break; there is nothing here to break.
+#
+# @example List the output ports
+#   MIDICommunicationsWindows::Output.all.each do |output|
+#     puts "#{output.id}: #{output.name}"
+#   end
+#
+# @example Send a note
+#   output = MIDICommunicationsWindows::Output.first
+#   output.open
+#   output.puts(0x90, 60, 100)
+#
+# @see https://learn.microsoft.com/en-us/windows/win32/multimedia/midi-reference Microsoft's MIDI reference
+#
+# @api public
+module MIDICommunicationsWindows
+end

data/midi-communications-windows.gemspec

@@ -0,0 +1,32 @@
+require_relative 'lib/midi-communications-windows/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'midi-communications-windows'
+  s.version     = MIDICommunicationsWindows::VERSION
+  s.date        = '2026-09-06'
+  s.summary     = 'Realtime MIDI IO with Ruby for Windows'
+  s.description = 'Access the Windows Multimedia (WinMM) MIDI API with Ruby.'
+  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://github.com/javier-sy/midi-communications-windows'
+  s.license     = 'LGPL-3.0-or-later'
+
+  s.required_ruby_version = '>= 2.7'
+
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/midi-communications-windows'
+  }
+
+  s.add_runtime_dependency 'ffi', '~> 1.15', '>= 1.15.4'
+
+  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

metadata

@@ -0,0 +1,220 @@
+--- !ruby/object:Gem::Specification
+name: midi-communications-windows
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Javier Sánchez Yeste
+bindir: bin
+cert_chain: []
+date: 2026-09-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.15.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.15.4
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+- !ruby/object:Gem::Dependency
+  name: shoulda-context
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Access the Windows Multimedia (WinMM) MIDI API with Ruby.
+email:
+- javier.sy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".version"
+- ".yardoc/checksums"
+- ".yardoc/complete"
+- ".yardoc/object_types"
+- ".yardoc/objects/root.dat"
+- ".yardoc/proxy_types"
+- ".yardopts"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- doc/MIDICommunicationsWindows.html
+- doc/MIDICommunicationsWindows/API.html
+- doc/MIDICommunicationsWindows/API/MIDIHdr.html
+- doc/MIDICommunicationsWindows/API/MIDIInCaps.html
+- doc/MIDICommunicationsWindows/API/MIDIOutCaps.html
+- doc/MIDICommunicationsWindows/API/MSG.html
+- doc/MIDICommunicationsWindows/Device.html
+- doc/MIDICommunicationsWindows/Device/ClassMethods.html
+- doc/MIDICommunicationsWindows/Device/InstanceMethods.html
+- doc/MIDICommunicationsWindows/Error.html
+- doc/MIDICommunicationsWindows/Input.html
+- doc/MIDICommunicationsWindows/Message.html
+- doc/MIDICommunicationsWindows/Output.html
+- doc/MIDICommunicationsWindows/TypeConversion.html
+- doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file.testing-on-windows.html
+- doc/file_list.html
+- doc/frames.html
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
+- docs/testing-on-windows.md
+- examples/input.rb
+- examples/list_ports.rb
+- examples/output.rb
+- examples/sysex_output.rb
+- lib/midi-communications-windows.rb
+- lib/midi-communications-windows/api.rb
+- lib/midi-communications-windows/device.rb
+- lib/midi-communications-windows/input.rb
+- lib/midi-communications-windows/message.rb
+- lib/midi-communications-windows/output.rb
+- lib/midi-communications-windows/type_conversion.rb
+- lib/midi-communications-windows/version.rb
+- midi-communications-windows.gemspec
+homepage: https://github.com/javier-sy/midi-communications-windows
+licenses:
+- LGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/javier-sy/midi-communications-windows
+  source_code_uri: https://github.com/javier-sy/midi-communications-windows
+  documentation_uri: https://www.rubydoc.info/gems/midi-communications-windows
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Realtime MIDI IO with Ruby for Windows
+test_files: []