midi-communications-windows 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7c6d6e900a9daa9c9a95c48a2c5b68b97bf02cd35694a0a5110cbe5ac9f1f9b
+  data.tar.gz: b2135a883c9648f77e6dbe99a5f1b25941c595f39c28dba3a5968d85f6b4d598
+SHA512:
+  metadata.gz: 294cfb3185f4fb694d5769fb43643260632772e9e7eea8be47691b5be92f65a64e51bf5f31b087a85a7e780d98532eca59a7311dec5d1b477cbc375b4836c884
+  data.tar.gz: bd6e9bc0bf14f7607d7d014f45e833311c874f56e58082c16bc7191030d050f8a33b4e7817b80dc8c92baa161f9c45754969b2ae837f2d37170a0a44193a2f8e

data/.gitignore

@@ -0,0 +1,8 @@
+**/.DS_Store
+*.gem
+.bundle
+.rspec
+.idea
+Gemfile.lock
+bin
+*.mindnode

data/.version

@@ -0,0 +1,6 @@
+# Configuración de versión para midi-communications-windows
+GEM_NAME="midi-communications-windows"
+MODULE_NAME="MIDICommunicationsWindows"
+VERSION_FILE="lib/midi-communications-windows/version.rb"
+GEMSPEC_FILE="midi-communications-windows.gemspec"
+TEST_COMMAND="bundle exec rake test"

data/.yardoc/checksums

@@ -0,0 +1,8 @@
+lib/midi-communications-windows.rb 30d820176659ee7ae703f6b02354e7674b3c1f5d
+lib/midi-communications-windows/api.rb ed16c89b3a2e85a37aed43962db414995a50294d
+lib/midi-communications-windows/input.rb 36e58891d1c604dd4b2f333382a4010660d47868
+lib/midi-communications-windows/device.rb 9f151193d144c298c064592ee21d44111f968d01
+lib/midi-communications-windows/output.rb 3069d46892268c529d999363bd05fac891e5f4fc
+lib/midi-communications-windows/message.rb 2390946620b244ec12a6b373e003304ef9c29e4d
+lib/midi-communications-windows/version.rb 3dbf5650d0b320f6164b3791f859d2551162dc0a
+lib/midi-communications-windows/type_conversion.rb dae7dc5109d955f4693920fa173f5c143dcb7bf1

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--title "MIDI Communications Windows API"
+--readme README.md
+--no-private
+--embed-mixins
+lib/**/*.rb
+-
+docs/testing-on-windows.md

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,176 @@
+# MIDI Communications Windows Layer
+
+[![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)
+
+**Realtime MIDI IO with Ruby for Windows.**
+
+Access the [Windows Multimedia (WinMM) MIDI API](https://learn.microsoft.com/en-us/windows/win32/multimedia/midi-reference) with Ruby.
+
+This library is part of a suite of Ruby libraries for MIDI:
+
+| Function | Library |
+| --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) |
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) |
+| Low level MIDI interface to Windows | [MIDI Communications Windows Layer](https://github.com/javier-sy/midi-communications-windows) (this library) |
+| 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)) |
+
+## Status
+
+**Early.** Everything is written and has been exercised end to end on Windows 11
+25H2 against system loopback endpoints: enumeration, short messages in both
+directions, System Exclusive in both directions including a message larger than
+the whole buffer queue, twenty open/close cycles, and the error path. What has
+not been exercised is anything needing real hardware — a physical interface slow
+enough to make `Output`'s System Exclusive wait mean something, and a port
+appearing or disappearing while the program runs.
+
+The version stays in the 0.0.x series because that was a virtual machine with no
+MIDI hardware in it, not because anything is known to be missing. It will not be
+published to RubyGems until a physical MIDI interface has closed the items
+[`docs/testing-on-windows.md`](docs/testing-on-windows.md) lists as untestable
+without one.
+
+That document is also how to rebuild the test environment: it is the procedure
+these measurements were taken with, including how to make two ports collide in
+WinMM's 31 characters of name.
+
+### One thing worth knowing before you use it
+
+`Input#gets` **waits**. It does not return an empty array when nothing has
+arrived; it blocks until something does, and then returns everything that
+accumulated. Calling it on a quiet port looks exactly like a hung program. That
+is deliberate — `Musa::Clock::InputMidiClock` reads in a loop with no delay of
+its own and relies on it — but it will surprise anyone arriving from an API that
+polls.
+
+## Requirements
+
+* [ffi](http://github.com/ffi/ffi)
+
+Nothing else. `winmm.dll` is part of Windows, so this gem binds a library that
+is already on the machine and ships no compiled artifact of its own.
+
+### Which versions of Windows
+
+**By construction, old ones.** Everything this gem calls is the oldest MIDI API
+Windows has — `midiInOpen`, `midiOutShortMsg`, `midiOutLongMsg` and their
+neighbours — plus three functions for a thread's message queue, `GetMessageW`,
+`PeekMessageW` and `PostThreadMessageW`. All of it, the Unicode entry points
+included, dates from the NT era. Nothing here calls Windows MIDI Services, which
+means nothing here needs Windows 11.
+
+What changes on an older system is not whether the gem works but what the
+platform gives it. Before Windows MIDI Services a MIDI port is **exclusive** —
+one program at a time — and there are no system loopback endpoints, so routing
+MIDI between applications on one machine needs a third-party driver such as
+loopMIDI. The same code, a poorer platform.
+
+A 32-bit Ruby should also be fine: the two size checks that only hold on 64-bit
+Windows are guarded, and the two that are checked everywhere describe structures
+whose layout does not depend on the word size.
+
+**None of which has been run.** The only system this has ever executed on is
+Windows 11 25H2, in a virtual machine, on an x64 Ruby under ARM emulation. The
+paragraphs above say what the code asks of Windows, not what has been observed;
+treat them as a reason to expect it to work rather than as a report that it does.
+
+Where the floor actually sits is a question about Ruby, not about this gem:
+RubyInstaller recommends Windows 10 or 11 and publishes no hard cutoff.
+
+## Installation
+
+If you're using Bundler, add this line to your application's Gemfile:
+
+`gem "midi-communications-windows"`
+
+Otherwise
+
+`gem install midi-communications-windows`
+
+## Documentation
+
+[rdoc](http://rubydoc.info/github/javier-sy/midi-communications-windows)
+
+## Why WinMM and not one of the newer Windows MIDI APIs
+
+Windows has three MIDI APIs a program could reach for, and as of February 2026
+the oldest is the right one for Ruby.
+
+**Windows MIDI Services** became generally available in Windows 11 in February
+2026, replacing the MIDI stack underneath. Rather than retiring the older APIs,
+Microsoft reconnected them to the new service, so a WinMM client needs nothing
+installed to reach what the new stack provides — including the loopback
+endpoints the system now creates itself, which is what previously required a
+third-party driver.
+
+Multi-client access arrives the same way, but **per endpoint, not per API**.
+Measured on Windows 11 25H2 through this library: two clients opened the same
+loopback input at once and both received every message, while a second open of
+the classic `wdmaud` software synthesiser was refused with "The specified device
+is already in use". Endpoints carried by the new transports are shared;
+endpoints still on the old drivers are exclusive, as they always were. On
+Windows 10 there is no Windows MIDI Services at all.
+
+**The Windows MIDI Services App SDK** offers MIDI 2.0 and UMP, neither of which
+this library needs: `midi-communications` and MusaDSL are MIDI 1.0 throughout.
+It is published only as WinRT, and Microsoft's guidance is that other languages
+obtain a WinRT projection from their toolchain. Ruby has none.
+
+**WinRT `Windows.Devices.Midi`** is, under the new stack, another compatibility
+layer onto the same service. It offers what WinMM offers, in exchange for
+hand-written COM.
+
+## Differences from the macOS layer
+
+The two libraries implement the same contract over platforms that do not have
+the same shape. Where they differ, they differ because the platforms do:
+
+* **`manufacturer` and `model` are `nil`.** WinMM reports `wMid` and `wPid`,
+  numeric codes from a manufacturer registry that stopped being maintained in
+  the 1990s and that class-compliant USB devices almost all answer with
+  Microsoft's. Core MIDI reports real strings. Inventing text from the codes
+  would describe the code table, not the hardware.
+* **`display_name` is the port name.** On macOS it is composed as
+  "manufacturer model (name)", which here would be a name wrapped in the
+  punctuation of two absent fields.
+* **Port ids are unique within a direction, not across both.** A WinMM port is
+  identified by its index among inputs or among outputs, and that index is what
+  is passed to `midiInOpen`. Core MIDI numbers endpoints of both directions from
+  one counter. Input 0 and output 0 are both valid here, and unrelated.
+* **Port names are truncated to 31 characters, and do not identify a port.**
+  That is all WinMM stores, and it drops the rest silently. Two loopback
+  endpoints whose names differed only past character 31 came back identical in
+  every field of `MIDIINCAPSW` — same name, same `wMid`, same `wPid`, same
+  `wTechnology` — distinguishable only by index. Core MIDI names are neither
+  truncated nor, in practice, ambiguous.
+* **Enumeration is not cached, but wrappers are reused.** The macOS layer reads
+  the device list once and keeps it, so a device plugged in later is never seen.
+  Here WinMM is asked on every call, and a port still present comes back as the
+  same object it was before, so opening a port and then reading from it works
+  whether or not the caller kept the reference.
+* **There is no packet-list parsing.** Core MIDI delivers a list of packets that
+  has to be walked; WinMM delivers one complete short message at a time, with
+  running status already resolved by the driver.
+
+## Relationship to midi-winmm
+
+This library is **not** derived from [midi-winmm](http://github.com/arirusso/midi-winmm),
+which was written in 2011 for 32-bit Ruby. Windows is LLP64: on a 64-bit Ruby,
+`unsigned long` is 32 bits while a `HANDLE` is 64, so that library's
+`typedef :ulong, :HANDLE` truncates every handle it obtains. It also reads port
+names through the ANSI entry points, which mangle any name that is not ASCII.
+Both are addressed here by construction; see the notes in
+`lib/midi-communications-windows/api.rb`.
+
+## Author
+
+* [Javier Sánchez Yeste](https://github.com/javier-sy)
+
+## License
+
+[MIDI Communications Windows Layer](https://github.com/javier-sy/midi-communications-windows) Copyright (c) 2026 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License

data/Rakefile

@@ -0,0 +1,13 @@
+$LOAD_PATH.prepend __dir__
+$LOAD_PATH.prepend File.join(__dir__, 'lib')
+
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task default: [:test]

data/doc/MIDICommunicationsWindows/API/MIDIHdr.html

@@ -0,0 +1,144 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: MIDICommunicationsWindows::API::MIDIHdr
+  
+    &mdash; MIDI Communications Windows API
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css">
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css">
+
+<script type="text/javascript">
+  pathId = "MIDICommunicationsWindows::API::MIDIHdr";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div id="main_progress" aria-hidden="true"></div>
+
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (M)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../MIDICommunicationsWindows.html" title="MIDICommunicationsWindows (module)">MIDICommunicationsWindows</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../API.html" title="MIDICommunicationsWindows::API (module)">API</a></span></span>
+     &raquo; 
+    <span class="title">MIDIHdr</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: MIDICommunicationsWindows::API::MIDIHdr
+  
+  
+  <span class="private note title">Private</span>
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">FFI::Struct</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">FFI::Struct</li>
+          
+            <li class="next">MIDICommunicationsWindows::API::MIDIHdr</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/midi-communications-windows/api.rb
+</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    <p class="note private">
+  <strong>This class is part of a private API.</strong>
+  You should avoid using this class if possible, as it may be removed or be changed in the future.
+</p>
+<p>A buffer handed to WinMM, used for System Exclusive in both directions.</p>
+<p><code>dwReserved</code> really is an array of eight pointer-sized words. Declaring it
+as a single word makes the structure too short, and WinMM writes past the
+end of it. This layout measures 120 bytes on 64-bit Windows, which is what
+WinMM there expects.</p>
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+
+
+
+
+
+
+
+  
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Sep  6 21:20:52 2026 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.45 (ruby-3.4.7).
+</div>
+
+    </div>
+  </body>
+</html>