midi-communications-windows 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fc6b5ad53dfa328b84bf63dcdb0660a2c5d6e00b18faec4eb5549a8f4baa116
-  data.tar.gz: 664db0add4987b5f180481b26e6d85e3ea66b7b645b59bda5a930bb6fe59eb6d
+  metadata.gz: fab76aff1317f582ff061ecac55ad7bdf25f27ed0ad1c55508f7481f88ae159a
+  data.tar.gz: b8d67bd3c739c80b5373ef1f6834ed73c20ccfec7301d539706d13703381d98b
 SHA512:
-  metadata.gz: 2bfafc2e6f554e568b37a2e53d4261734d858da411d42a8a04a0d3cc3ccbb7bb5fe7d62b7e243c9ca62a0a3804cbf451f02372c86b4b9fb88899a1c872c0e52b
-  data.tar.gz: 1718a6d1111ab6ff8e4cdbb79d6bc2c3de18aed3478cd5d997283e8c437657d4b3c91670edebaddd661ff8d4b08b7d12ac4541cd3e38284c65811a219eab90ff
+  metadata.gz: bd3861ebb4b96e659894b35810a5db436be4901a631ce13f06ae7401d72846d25b32b408f5607cb35020045756ba0e20bc375f4c57947f73f3a45bd303dad8ae
+  data.tar.gz: 559595e2a885245f981d4d8bd90376fc584a4d15ebd475c5e5391b81dee1aeafb5b3ea82551af4cae31f717d0f5d940d3b23d5d76984eb158fbd0f55697740b0

data/.yardoc/checksums

@@ -4,5 +4,5 @@ lib/midi-communications-windows/input.rb 36e58891d1c604dd4b2f333382a4010660d4786
 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 4804d6731ca80a4f6f679dd5585ed1b2c7517513
+lib/midi-communications-windows/version.rb 902ae38c68bbfd2670740b7d7bb6a342f77cbb68
 lib/midi-communications-windows/type_conversion.rb dae7dc5109d955f4693920fa173f5c143dcb7bf1

data/README.md

@@ -19,66 +19,32 @@ This library is part of a suite of Ruby libraries for MIDI:
 | 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
+You will normally reach it through
+[MIDI Communications](https://github.com/javier-sy/midi-communications), which
+depends on it and selects it on Windows. It implements that gem's physical layer
+contract; anything about how ports behave is documented there, in
+`MIDICommunications::PhysicalLayer`.
 
-**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.
+## Features
 
-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.
+* Simplified API
+* Input and output on multiple devices concurrently
+* Generalized handling of different MIDI Message types (including SysEx)
+* Timestamped input events
+* Patch MIDI via software to other programs using a loopback endpoint
+* No compiled artifact: `winmm.dll` is part of Windows
 
-How those measurements were taken, and what a session with real hardware still
-has to close, is written down in
-[`dev/testing-on-windows.md`](dev/testing-on-windows.md).
+Runnable examples of the API are in [`examples/`](examples).
 
-### One thing worth knowing before you use it
+## Status
 
-`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.
+**Early.** Tested on Windows 11 without external MIDI devices. Everything works
+against loopback ports; running it against real hardware is still pending.
 
 ## 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:
@@ -91,78 +57,7 @@ Otherwise
 
 ## 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`.
+[rdoc](https://www.rubydoc.info/gems/midi-communications-windows)
 
 ## Author
 

data/doc/MIDICommunicationsWindows/API/MIDIHdr.html

@@ -134,7 +134,7 @@ WinMM there expects.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/API/MIDIInCaps.html

@@ -132,7 +132,7 @@ declared as <code>:uint16</code> so that reading it cannot split a character in
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/API/MIDIOutCaps.html

@@ -130,7 +130,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/API/MSG.html

@@ -133,7 +133,7 @@ is 48 bytes on 64-bit Windows, which is what the queue functions expect.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/API.html

@@ -971,7 +971,7 @@ than showing a replacement character.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Device/ClassMethods.html

@@ -355,7 +355,7 @@ back as the same object as before; see <span class='object_link'><a href="../Dev
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Device/InstanceMethods.html

@@ -1086,7 +1086,7 @@ may already hold.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Device.html

@@ -978,7 +978,7 @@ the reserved id <code>-1</code> and does not count among its devices.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Error.html

@@ -428,7 +428,7 @@ for instance</p></div>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Input.html

@@ -1544,7 +1544,7 @@ may already hold.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Message.html

@@ -690,7 +690,7 @@ byte calls for</p></div>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/Output.html

@@ -1687,7 +1687,7 @@ else, and this is where the two part company.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows/TypeConversion.html

@@ -359,7 +359,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/MIDICommunicationsWindows.html

@@ -184,7 +184,7 @@ RubyGems is where installations break; there is nothing here to break.</p>
 
 </div>
         </dt>
-        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.0.4</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.1.0</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
       
     </dl>
   
@@ -200,7 +200,7 @@ RubyGems is where installations break; there is nothing here to break.</p>
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/_index.html

@@ -249,7 +249,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:17 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/file.README.html

@@ -103,122 +103,35 @@
 </tr>
 </tbody>
 </table>
+<p>You will normally reach it through
+<a href="https://github.com/javier-sy/midi-communications">MIDI Communications</a>, which
+depends on it and selects it on Windows. It implements that gem's physical layer
+contract; anything about how ports behave is documented there, in
+<code>MIDICommunications::PhysicalLayer</code>.</p>
+<h2 id="Features">Features</h2>
+<ul>
+<li>Simplified API</li>
+<li>Input and output on multiple devices concurrently</li>
+<li>Generalized handling of different MIDI Message types (including SysEx)</li>
+<li>Timestamped input events</li>
+<li>Patch MIDI via software to other programs using a loopback endpoint</li>
+<li>No compiled artifact: <code>winmm.dll</code> is part of Windows</li>
+</ul>
+<p>Runnable examples of the API are in <a href="examples"><code>examples/</code></a>.</p>
 <h2 id="Status">Status</h2>
-<p><strong>Early.</strong> 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 <code>Output</code>'s System Exclusive wait mean something, and a port
-appearing or disappearing while the program runs.</p>
-<p>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.</p>
-<p>How those measurements were taken, and what a session with real hardware still
-has to close, is written down in
-<a href="dev/testing-on-windows.md"><code>dev/testing-on-windows.md</code></a>.</p>
-<h3 id="One_thing_worth_knowing_before_you_use_it">One thing worth knowing before you use it</h3>
-<p><code>Input#gets</code> <strong>waits</strong>. 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 — <code>Musa::Clock::InputMidiClock</code> 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.</p>
+<p><strong>Early.</strong> Tested on Windows 11 without external MIDI devices. Everything works
+against loopback ports; running it against real hardware is still pending.</p>
 <h2 id="Requirements">Requirements</h2>
 <ul>
 <li><a href="http://github.com/ffi/ffi">ffi</a></li>
 </ul>
-<p>Nothing else. <code>winmm.dll</code> is part of Windows, so this gem binds a library that
-is already on the machine and ships no compiled artifact of its own.</p>
-<h3 id="Which_versions_of_Windows">Which versions of Windows</h3>
-<p><strong>By construction, old ones.</strong> Everything this gem calls is the oldest MIDI API
-Windows has — <code>midiInOpen</code>, <code>midiOutShortMsg</code>, <code>midiOutLongMsg</code> and their
-neighbours — plus three functions for a thread's message queue, <code>GetMessageW</code>,
-<code>PeekMessageW</code> and <code>PostThreadMessageW</code>. 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.</p>
-<p>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 <strong>exclusive</strong> —
-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.</p>
-<p>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.</p>
-<p><strong>None of which has been run.</strong> 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.</p>
-<p>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.</p>
 <h2 id="Installation">Installation</h2>
 <p>If you're using Bundler, add this line to your application's Gemfile:</p>
 <p><code>gem &quot;midi-communications-windows&quot;</code></p>
 <p>Otherwise</p>
 <p><code>gem install midi-communications-windows</code></p>
 <h2 id="Documentation">Documentation</h2>
-<p><a href="http://rubydoc.info/github/javier-sy/midi-communications-windows">rdoc</a></p>
-<h2 id="Why_WinMM_and_not_one_of_the_newer_Windows_MIDI_APIs">Why WinMM and not one of the newer Windows MIDI APIs</h2>
-<p>Windows has three MIDI APIs a program could reach for, and as of February 2026
-the oldest is the right one for Ruby.</p>
-<p><strong>Windows MIDI Services</strong> 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.</p>
-<p>Multi-client access arrives the same way, but <strong>per endpoint, not per API</strong>.
-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 <code>wdmaud</code> software synthesiser was refused with &quot;The specified device
-is already in use&quot;. 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.</p>
-<p><strong>The Windows MIDI Services App SDK</strong> offers MIDI 2.0 and UMP, neither of which
-this library needs: <code>midi-communications</code> 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.</p>
-<p><strong>WinRT <code>Windows.Devices.Midi</code></strong> is, under the new stack, another compatibility
-layer onto the same service. It offers what WinMM offers, in exchange for
-hand-written COM.</p>
-<h2 id="Differences_from_the_macOS_layer">Differences from the macOS layer</h2>
-<p>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:</p>
-<ul>
-<li><strong><code>manufacturer</code> and <code>model</code> are <code>nil</code>.</strong> WinMM reports <code>wMid</code> and <code>wPid</code>,
-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.</li>
-<li><strong><code>display_name</code> is the port name.</strong> On macOS it is composed as
-&quot;manufacturer model (name)&quot;, which here would be a name wrapped in the
-punctuation of two absent fields.</li>
-<li><strong>Port ids are unique within a direction, not across both.</strong> A WinMM port is
-identified by its index among inputs or among outputs, and that index is what
-is passed to <code>midiInOpen</code>. Core MIDI numbers endpoints of both directions from
-one counter. Input 0 and output 0 are both valid here, and unrelated.</li>
-<li><strong>Port names are truncated to 31 characters, and do not identify a port.</strong>
-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 <code>MIDIINCAPSW</code> — same name, same <code>wMid</code>, same <code>wPid</code>, same
-<code>wTechnology</code> — distinguishable only by index. Core MIDI names are neither
-truncated nor, in practice, ambiguous.</li>
-<li><strong>Enumeration is not cached, but wrappers are reused.</strong> 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.</li>
-<li><strong>There is no packet-list parsing.</strong> 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.</li>
-</ul>
-<h2 id="Relationship_to_midi_winmm">Relationship to midi-winmm</h2>
-<p>This library is <strong>not</strong> derived from <a href="http://github.com/arirusso/midi-winmm">midi-winmm</a>,
-which was written in 2011 for 32-bit Ruby. Windows is LLP64: on a 64-bit Ruby,
-<code>unsigned long</code> is 32 bits while a <code>HANDLE</code> is 64, so that library's
-<code>typedef :ulong, :HANDLE</code> 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
-<code>lib/midi-communications-windows/api.rb</code>.</p>
+<p><a href="https://www.rubydoc.info/gems/midi-communications-windows">rdoc</a></p>
 <h2 id="Author">Author</h2>
 <ul>
 <li><a href="https://github.com/javier-sy">Javier Sánchez Yeste</a></li>
@@ -227,7 +140,7 @@ Both are addressed here by construction; see the notes in
 <p><a href="https://github.com/javier-sy/midi-communications-windows">MIDI Communications Windows Layer</a> Copyright (c) 2026 <a href="https://yeste.studio">Javier Sánchez Yeste</a>, licensed under LGPL 3.0 License</p></div></div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/index.html

@@ -103,122 +103,35 @@
 </tr>
 </tbody>
 </table>
+<p>You will normally reach it through
+<a href="https://github.com/javier-sy/midi-communications">MIDI Communications</a>, which
+depends on it and selects it on Windows. It implements that gem's physical layer
+contract; anything about how ports behave is documented there, in
+<code>MIDICommunications::PhysicalLayer</code>.</p>
+<h2 id="Features">Features</h2>
+<ul>
+<li>Simplified API</li>
+<li>Input and output on multiple devices concurrently</li>
+<li>Generalized handling of different MIDI Message types (including SysEx)</li>
+<li>Timestamped input events</li>
+<li>Patch MIDI via software to other programs using a loopback endpoint</li>
+<li>No compiled artifact: <code>winmm.dll</code> is part of Windows</li>
+</ul>
+<p>Runnable examples of the API are in <a href="examples"><code>examples/</code></a>.</p>
 <h2 id="Status">Status</h2>
-<p><strong>Early.</strong> 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 <code>Output</code>'s System Exclusive wait mean something, and a port
-appearing or disappearing while the program runs.</p>
-<p>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.</p>
-<p>How those measurements were taken, and what a session with real hardware still
-has to close, is written down in
-<a href="dev/testing-on-windows.md"><code>dev/testing-on-windows.md</code></a>.</p>
-<h3 id="One_thing_worth_knowing_before_you_use_it">One thing worth knowing before you use it</h3>
-<p><code>Input#gets</code> <strong>waits</strong>. 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 — <code>Musa::Clock::InputMidiClock</code> 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.</p>
+<p><strong>Early.</strong> Tested on Windows 11 without external MIDI devices. Everything works
+against loopback ports; running it against real hardware is still pending.</p>
 <h2 id="Requirements">Requirements</h2>
 <ul>
 <li><a href="http://github.com/ffi/ffi">ffi</a></li>
 </ul>
-<p>Nothing else. <code>winmm.dll</code> is part of Windows, so this gem binds a library that
-is already on the machine and ships no compiled artifact of its own.</p>
-<h3 id="Which_versions_of_Windows">Which versions of Windows</h3>
-<p><strong>By construction, old ones.</strong> Everything this gem calls is the oldest MIDI API
-Windows has — <code>midiInOpen</code>, <code>midiOutShortMsg</code>, <code>midiOutLongMsg</code> and their
-neighbours — plus three functions for a thread's message queue, <code>GetMessageW</code>,
-<code>PeekMessageW</code> and <code>PostThreadMessageW</code>. 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.</p>
-<p>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 <strong>exclusive</strong> —
-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.</p>
-<p>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.</p>
-<p><strong>None of which has been run.</strong> 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.</p>
-<p>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.</p>
 <h2 id="Installation">Installation</h2>
 <p>If you're using Bundler, add this line to your application's Gemfile:</p>
 <p><code>gem &quot;midi-communications-windows&quot;</code></p>
 <p>Otherwise</p>
 <p><code>gem install midi-communications-windows</code></p>
 <h2 id="Documentation">Documentation</h2>
-<p><a href="http://rubydoc.info/github/javier-sy/midi-communications-windows">rdoc</a></p>
-<h2 id="Why_WinMM_and_not_one_of_the_newer_Windows_MIDI_APIs">Why WinMM and not one of the newer Windows MIDI APIs</h2>
-<p>Windows has three MIDI APIs a program could reach for, and as of February 2026
-the oldest is the right one for Ruby.</p>
-<p><strong>Windows MIDI Services</strong> 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.</p>
-<p>Multi-client access arrives the same way, but <strong>per endpoint, not per API</strong>.
-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 <code>wdmaud</code> software synthesiser was refused with &quot;The specified device
-is already in use&quot;. 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.</p>
-<p><strong>The Windows MIDI Services App SDK</strong> offers MIDI 2.0 and UMP, neither of which
-this library needs: <code>midi-communications</code> 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.</p>
-<p><strong>WinRT <code>Windows.Devices.Midi</code></strong> is, under the new stack, another compatibility
-layer onto the same service. It offers what WinMM offers, in exchange for
-hand-written COM.</p>
-<h2 id="Differences_from_the_macOS_layer">Differences from the macOS layer</h2>
-<p>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:</p>
-<ul>
-<li><strong><code>manufacturer</code> and <code>model</code> are <code>nil</code>.</strong> WinMM reports <code>wMid</code> and <code>wPid</code>,
-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.</li>
-<li><strong><code>display_name</code> is the port name.</strong> On macOS it is composed as
-&quot;manufacturer model (name)&quot;, which here would be a name wrapped in the
-punctuation of two absent fields.</li>
-<li><strong>Port ids are unique within a direction, not across both.</strong> A WinMM port is
-identified by its index among inputs or among outputs, and that index is what
-is passed to <code>midiInOpen</code>. Core MIDI numbers endpoints of both directions from
-one counter. Input 0 and output 0 are both valid here, and unrelated.</li>
-<li><strong>Port names are truncated to 31 characters, and do not identify a port.</strong>
-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 <code>MIDIINCAPSW</code> — same name, same <code>wMid</code>, same <code>wPid</code>, same
-<code>wTechnology</code> — distinguishable only by index. Core MIDI names are neither
-truncated nor, in practice, ambiguous.</li>
-<li><strong>Enumeration is not cached, but wrappers are reused.</strong> 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.</li>
-<li><strong>There is no packet-list parsing.</strong> 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.</li>
-</ul>
-<h2 id="Relationship_to_midi_winmm">Relationship to midi-winmm</h2>
-<p>This library is <strong>not</strong> derived from <a href="http://github.com/arirusso/midi-winmm">midi-winmm</a>,
-which was written in 2011 for 32-bit Ruby. Windows is LLP64: on a 64-bit Ruby,
-<code>unsigned long</code> is 32 bits while a <code>HANDLE</code> is 64, so that library's
-<code>typedef :ulong, :HANDLE</code> 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
-<code>lib/midi-communications-windows/api.rb</code>.</p>
+<p><a href="https://www.rubydoc.info/gems/midi-communications-windows">rdoc</a></p>
 <h2 id="Author">Author</h2>
 <ul>
 <li><a href="https://github.com/javier-sy">Javier Sánchez Yeste</a></li>
@@ -227,7 +140,7 @@ Both are addressed here by construction; see the notes in
 <p><a href="https://github.com/javier-sy/midi-communications-windows">MIDI Communications Windows Layer</a> Copyright (c) 2026 <a href="https://yeste.studio">Javier Sánchez Yeste</a>, licensed under LGPL 3.0 License</p></div></div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

data/doc/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Sep  7 00:14:18 2026 by
+  Generated on Mon Sep  7 01:25:12 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>

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: midi-communications-windows
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Javier Sánchez Yeste