RubyGems - midi-communications-windows - Versions diffs - 0.0.3 - Mend

midi-communications-windows 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

checksums.yaml +7 -0
data/.gitignore +8 -0
data/.version +6 -0
data/.yardoc/checksums +8 -0
data/.yardoc/complete +0 -0
data/.yardoc/object_types +0 -0
data/.yardoc/objects/root.dat +0 -0
data/.yardoc/proxy_types +0 -0
data/.yardopts +8 -0
data/Gemfile +3 -0
data/LICENSE +165 -0
data/README.md +176 -0
data/Rakefile +13 -0
data/doc/MIDICommunicationsWindows/API/MIDIHdr.html +144 -0
data/doc/MIDICommunicationsWindows/API/MIDIInCaps.html +142 -0
data/doc/MIDICommunicationsWindows/API/MIDIOutCaps.html +140 -0
data/doc/MIDICommunicationsWindows/API/MSG.html +143 -0
data/doc/MIDICommunicationsWindows/API.html +981 -0
data/doc/MIDICommunicationsWindows/Device/ClassMethods.html +365 -0
data/doc/MIDICommunicationsWindows/Device/InstanceMethods.html +1096 -0
data/doc/MIDICommunicationsWindows/Device.html +988 -0
data/doc/MIDICommunicationsWindows/Error.html +438 -0
data/doc/MIDICommunicationsWindows/Input.html +1554 -0
data/doc/MIDICommunicationsWindows/Message.html +700 -0
data/doc/MIDICommunicationsWindows/Output.html +1697 -0
data/doc/MIDICommunicationsWindows/TypeConversion.html +369 -0
data/doc/MIDICommunicationsWindows.html +210 -0
data/doc/_index.html +262 -0
data/doc/class_list.html +54 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +206 -0
data/doc/css/style.css +1089 -0
data/doc/file.README.html +240 -0
data/doc/file.testing-on-windows.html +253 -0
data/doc/file_list.html +64 -0
data/doc/frames.html +22 -0
data/doc/index.html +240 -0
data/doc/js/app.js +801 -0
data/doc/js/full_list.js +334 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +382 -0
data/doc/top-level-namespace.html +112 -0
data/docs/testing-on-windows.md +222 -0
data/examples/input.rb +27 -0
data/examples/list_ports.rb +17 -0
data/examples/output.rb +22 -0
data/examples/sysex_output.rb +15 -0
data/lib/midi-communications-windows/api.rb +340 -0
data/lib/midi-communications-windows/device.rb +310 -0
data/lib/midi-communications-windows/input.rb +486 -0
data/lib/midi-communications-windows/message.rb +133 -0
data/lib/midi-communications-windows/output.rb +206 -0
data/lib/midi-communications-windows/type_conversion.rb +20 -0
data/lib/midi-communications-windows/version.rb +4 -0
data/lib/midi-communications-windows.rb +76 -0
data/midi-communications-windows.gemspec +32 -0
metadata +220 -0

data/doc/file.README.html ADDED Viewed

@@ -0,0 +1,240 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  File: README
+    &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 = "README";
+  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="file_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</a> &raquo;
+    <span class="title">File: README</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"><div id='filecontents'><h1 id="MIDI_Communications_Windows_Layer">MIDI Communications Windows Layer</h1>
+<p><a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-2.7+-red.svg" alt="Ruby Version" /></a>
+<a href="https://www.gnu.org/licenses/lgpl-3.0.html"><img src="https://img.shields.io/badge/license-LGPL--3.0--or--later-blue.svg" alt="License" /></a></p>
+<p><strong>Realtime MIDI IO with Ruby for Windows.</strong></p>
+<p>Access the <a href="https://learn.microsoft.com/en-us/windows/win32/multimedia/midi-reference">Windows Multimedia (WinMM) MIDI API</a> with Ruby.</p>
+<p>This library is part of a suite of Ruby libraries for MIDI:</p>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Library</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>MIDI Events representation</td>
+<td><a href="https://github.com/javier-sy/midi-events">MIDI Events</a></td>
+</tr>
+<tr>
+<td>MIDI Data parsing</td>
+<td><a href="https://github.com/javier-sy/midi-parser">MIDI Parser</a></td>
+</tr>
+<tr>
+<td>MIDI communication with Instruments and Control Surfaces</td>
+<td><a href="https://github.com/javier-sy/midi-communications">MIDI Communications</a></td>
+</tr>
+<tr>
+<td>Low level MIDI interface to MacOS</td>
+<td><a href="https://github.com/javier-sy/midi-communications-macos">MIDI Communications MacOS Layer</a></td>
+</tr>
+<tr>
+<td>Low level MIDI interface to Windows</td>
+<td><a href="https://github.com/javier-sy/midi-communications-windows">MIDI Communications Windows Layer</a> (this library)</td>
+</tr>
+<tr>
+<td>Low level MIDI interface to Linux</td>
+<td><strong>TO DO</strong> (by now <a href="https://github.com/javier-sy/midi-communications">MIDI Communications</a> uses <a href="http://github.com/arirusso/alsa-rawmidi">alsa-rawmidi</a>)</td>
+</tr>
+<tr>
+<td>Low level MIDI interface to JRuby</td>
+<td><strong>TO DO</strong> (by now <a href="https://github.com/javier-sy/midi-communications">MIDI Communications</a> uses <a href="http://github.com/arirusso/midi-jruby">midi-jruby</a>)</td>
+</tr>
+</tbody>
+</table>
+<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. It will not be
+published to RubyGems until a physical MIDI interface has closed the items
+<a href="docs/testing-on-windows.md"><code>docs/testing-on-windows.md</code></a> lists as untestable
+without one.</p>
+<p>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.</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>
+<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>
+<h2 id="Author">Author</h2>
+<ul>
+<li><a href="https://github.com/javier-sy">Javier Sánchez Yeste</a></li>
+</ul>
+<h2 id="License">License</h2>
+<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 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>

data/doc/file.testing-on-windows.html ADDED Viewed

@@ -0,0 +1,253 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  File: testing-on-windows
+    &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 = "testing-on-windows";
+  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="file_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</a> &raquo;
+    <span class="title">File: testing-on-windows</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"><div id='filecontents'><h1 id="Testing_this_gem_on_Windows_without_MIDI_hardware">Testing this gem on Windows without MIDI hardware</h1>
+<p><em>Written 2026-09-06. Section 1 is the part with a shelf life: it describes
+software that was in preview at the time, which Microsoft's release notes said
+was headed for Windows 11 25H2 and later during the last week of November 2026.
+If that has happened, most of section 1 collapses into &quot;nothing to install&quot; and
+the rest still applies.</em></p>
+<p>This is <strong>the procedure the library was measured with</strong>, not a promise that it
+works on another machine. All of it ran once, on one particular installation.
+Where something was checked, it says so; where it was not, it says that too.</p>
+<p>The machine was:</p>
+<p>| | |
+|---|---|
+| Windows | 11 25H2, build <strong>26200.9278</strong> |
+| CPU | ARM64 — a VMware VM on Apple silicon |
+| Ruby | 3.4.10 <code>x64-mingw-ucrt</code>, <strong>emulated</strong> under Prism (no ARM64 Ruby present) |
+| ffi | 1.17.4 <code>x64-mingw-ucrt</code>, precompiled binary |
+| MIDI hardware | <strong>none</strong> — no USB device passed through to the guest |</p>
+<p>That last row is why this document exists: with no hardware, a loopback pair is
+the only way to exercise input and output at the same time.</p>
+<p>Nothing measured on this setup says anything about <strong>timing</strong>. Emulation inside
+a virtual machine; latency and jitter need real hardware and a native Ruby.</p>
+<hr />
+<h2 id="1__What_has_to_be_installed">1. What has to be installed</h2>
+<p>Windows 11 25H2 ships <strong>Windows MIDI Services</strong> in the box: the <code>midisrv</code>
+service (<code>C:\Windows\System32\midisrv.exe</code>) and the <code>wdmaud2.drv</code> shim,
+registered as <code>midi1</code> under
+<code>HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Drivers32</code>. That shim is what
+makes endpoints from the new stack <strong>visible to WinMM</strong> without this gem doing
+anything special, and therefore what makes this setup able to test a gem that
+speaks only WinMM.</p>
+<p>What is <em>not</em> in the box are the MIDI 1.0 loopback transport and the tools. Those
+come from the [<code>microsoft/MIDI</code>] repository, release <code>inbox-dev-preview-6</code>:</p>
+<ul>
+<li><code>Windows.MIDI.Services.Basic.MIDI.1.0.Loopback.Preview.1.0.18-preview.3-arm64.exe</code></li>
+<li><code>Windows.MIDI.Services.Tools.0.99.64-devpreview.6-arm64.exe</code></li>
+</ul>
+<p>There are <code>-x64</code> variants of both. The measuring machine used the <strong>native ARM64</strong>
+ones (PE header <code>0xAA64</code>) even though the Ruby was emulated x64: the gem talks to
+<code>winmm.dll</code>, and Windows handles the crossing.</p>
+<p>The Network and Bluetooth transports from the same release are not needed.</p>
+<h3 id="Warnings_that_are_not_optional">Warnings that are not optional</h3>
+<ul>
+<li><strong>These are unsigned preview binaries.</strong> The release notes require Windows
+<strong>Developer Mode</strong>, and are explicit: <em>&quot;There are almost certainly bugs and
+missing/incomplete features.&quot;</em> This is not production software.</li>
+<li><strong>Do not redistribute them.</strong> The release's permitted-use table forbids it. A
+repository should link to the release and never host the installers.</li>
+<li>Minimum system version declared: <strong>Windows 11 25H2</strong>.</li>
+<li>Downloaded through a browser they carry Mark of the Web and SmartScreen will
+object; <code>Unblock-File</code> clears it. Fetched with <code>Invoke-WebRequest</code> they do not.</li>
+</ul>
+<h2 id="2__Installing">2. Installing</h2>
+<p>Both installers are <strong>WiX bundles</strong>, so they accept <code>/quiet</code>, <code>/norestart</code> and
+<code>/log</code>. Both need <strong>elevation</strong>, and Developer Mode writes to <code>HKLM</code>, so it is
+worth doing the whole thing in one elevated script and getting one UAC prompt.</p>
+<p>The release notes fix the order: <strong>loopback transport first, tools second.</strong></p>
+<pre class="code powershell"><code class="powershell"># --- 1. Developer Mode (the key may not exist)
+$k = &#39;HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock&#39;
+if (-not (Test-Path $k)) { New-Item $k -Force | Out-Null }
+Set-ItemProperty $k -Name AllowDevelopmentWithoutDevLicense -Value 1 -Type DWord
+Set-ItemProperty $k -Name AllowAllTrustedApps -Value 1 -Type DWord
+# --- 2. installers, in this order
+Start-Process -Wait -FilePath &#39;&lt;...&gt;Basic.MIDI.1.0.Loopback.Preview...-arm64.exe&#39; `
+  -ArgumentList &#39;/quiet&#39;,&#39;/norestart&#39;,&#39;/log&#39;,&#39;loopback.log&#39;
+Start-Process -Wait -FilePath &#39;&lt;...&gt;Tools.0.99.64-devpreview.6-arm64.exe&#39; `
+  -ArgumentList &#39;/quiet&#39;,&#39;/norestart&#39;,&#39;/log&#39;,&#39;tools.log&#39;
+</code></pre>
+<p><strong>Both return exit <code>3010</code></strong>, which is <code>ERROR_SUCCESS_REBOOT_REQUIRED</code>: installed
+correctly, reboot pending. The measuring machine <strong>was not rebooted</strong>, and every
+measurement was taken that way. If something behaves oddly, that reboot is the
+first suspect.</p>
+<p>To check the transport registered:</p>
+<pre class="code powershell"><code class="powershell">Get-ChildItem &#39;HKLM:\SOFTWARE\Microsoft\Windows MIDI Services\Transport Plugins&#39;
+# Midi2BasicLoopbackMidiTransport should appear, with Enabled = 1
+</code></pre>
+<h3 id="_midi_exe__and_the_PATH"><code>midi.exe</code> and the PATH</h3>
+<p>The console lands at:</p>
+<pre class="code ruby"><code class="ruby">C:\Program Files\Windows MIDI Services\Tools\Console\midi.exe
+</code></pre>
+<p>The installer <strong>does</strong> add it to the machine PATH, but <strong>a shell opened before
+installing still has the old environment</strong> and will say <code>midi</code> does not exist. In
+a fresh shell, <code>midi</code> is enough; in the installing shell, use the full path. This
+detail cost time and produced one wrong report before it was noticed.</p>
+<h2 id="3__Creating_the_loopback_pair">3. Creating the loopback pair</h2>
+<pre class="code powershell"><code class="powershell">$midi = &#39;C:\Program Files\Windows MIDI Services\Tools\Console\midi.exe&#39;
+&amp; $midi basic-loopback create --name &quot;Reloj Bitwig ñ prueba de longitud&quot;
+&amp; $midi basic-loopback list
+</code></pre>
+<p>Options for <code>create</code>:</p>
+<table>
+<thead>
+<tr>
+<th>option</th>
+<th>what it does</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>-n</code>, <code>--name</code></td>
+<td>the endpoint's name</td>
+</tr>
+<tr>
+<td><code>-u</code>, <code>--unique-identifier</code></td>
+<td>an identifier of your own</td>
+</tr>
+<tr>
+<td><code>-s</code>, <code>--save-to-config</code></td>
+<td><strong>persists it in the system configuration</strong></td>
+</tr>
+</tbody>
+</table>
+<p><strong>Without <code>--save-to-config</code> a loopback is temporary</strong>: it disappears when
+<code>midisrv</code> or the machine restarts, and nothing is written to disk. Every
+measurement was taken that way, deliberately. <code>--save-to-config</code> does modify the
+user's system configuration — ask before using it.</p>
+<p>A <code>create</code> returns an <strong>Association Id</strong>, a GUID. Keep it: it is the only thing
+that will remove the loopback again.</p>
+<h3 id="Checking_through_WinMM__which_is_what_the_gem_sees">Checking through WinMM, which is what the gem sees</h3>
+<pre class="code ruby"><code class="ruby">ruby -Ilib examples/list_ports.rb
+</code></pre>
+<p>One loopback shows up as <strong>one input and one output with the same name, byte for
+byte</strong>. With two loopbacks created, enumeration gives 2 inputs and 3 outputs —
+the third being the <em>Microsoft GS Wavetable Synth</em>, which is always there.</p>
+<h2 id="4__The_name_collision_recipe">4. The name-collision recipe</h2>
+<p>WinMM stores <strong>31 characters</strong> of a name (<code>MAXPNAMELEN</code> is 32, less the NUL) and
+drops the rest <strong>silently</strong>. To reproduce the case where two distinct ports are
+indistinguishable, create two loopbacks whose <strong>first 31 characters match</strong>:</p>
+<pre class="code powershell"><code class="powershell">&amp; $midi basic-loopback create --name &quot;Reloj Bitwig ñ prueba de longitud&quot;
+&amp; $midi basic-loopback create --name &quot;Reloj Bitwig ñ prueba de longitud DOS&quot;
+</code></pre>
+<p>The first is 33 characters, the second 37; both truncate to
+<code>Reloj Bitwig ñ prueba de longit</code>. In <code>MIDIINCAPSW</code>/<code>MIDIOUTCAPSW</code> they come back
+<strong>identical field by field</strong>: same name, same <code>wMid</code> (1), same <code>wPid</code> (25 for
+inputs, 26 for outputs), same <code>vDriverVersion</code>, same <code>wTechnology</code>. Only the
+index separates them.</p>
+<p>If you change the names, keep the character counts working — the recipe depends
+on one being longer than 31 and both agreeing up to that point.</p>
+<p>The truncation happens <strong>upstream of WinMM</strong>: <code>midi enumerate midi-services-endpoints</code> shows the service already holding the 31-character name.
+Whether the console or the service truncates was not determined; for the gem it
+makes no difference.</p>
+<p>The <code>ñ</code> survives intact (<code>U+00F1</code> in the UTF-16LE dump), which is what validates
+the <strong>W</strong> entry points against a genuinely non-ASCII character.</p>
+<h2 id="5__Removing">5. Removing</h2>
+<pre class="code powershell"><code class="powershell">&amp; $midi basic-loopback remove --association-id &quot;{bfba125e-3aca-446c-9b94-692a70153034}&quot;
+</code></pre>
+<p><strong>The braces around the GUID are required.</strong> <code>list</code> prints the id without them;
+they have to be added.</p>
+<p>Afterwards, check the machine is back where it started — with <code>list</code>, and better
+still by enumerating through WinMM: with no loopbacks there should be <strong>0 inputs
+and 1 output</strong>.</p>
+<h2 id="6__What_this_setup_can_test__and_what_it_cannot">6. What this setup can test, and what it cannot</h2>
+<p>Exercised with it, and working: enumeration with colliding names, short messages
+in all three lengths (3, 2 and 1 bytes), accumulation in <code>gets</code>, System Exclusive
+both ways at 200, 3000 and 5000 bytes, buffer recycling, closing and reopening,
+and the propagation of an error from opening a port.</p>
+<p><strong>Not testable with this setup</strong>, and therefore still untested:</p>
+<ul>
+<li><strong><code>SYSEX_TIMEOUT</code> / <code>Output#wait_until_sent</code>.</strong> The only real output device is
+the <em>GS Wavetable Synth</em>, a software synthesiser that marks <code>MHDR_DONE</code> in
+under a millisecond because there is no wire. This needs a physical interface.</li>
+<li><strong><code>RESET_TIMEOUT</code> / <code>Input#await_returned_buffers</code>.</strong> It never came close:
+closes took between 4 and 21 ms against a one-second bound. The
+device-went-away path needs something to unplug.</li>
+<li><strong>Renumbering in <code>Device.enumerate</code>.</strong> Needs a port to actually appear or go.</li>
+<li><strong><code>MM_MIM_LONGERROR</code>.</strong> None could be provoked, not even with a System
+Exclusive message larger than the entire buffer queue. The code handling it is
+unexercised — its presence has been shown harmless, which is not the same
+thing.</li>
+<li><strong>That an input and an output of the same device share a name.</strong> Established
+for a loopback, where they are literally the same device. Not for a real USB
+interface.</li>
+<li><strong>Any measurement of time.</strong></li>
+</ul>
+<p>Those are the items a session with real hardware should close.</p>
+<h2 id="7__One_finding_from_here_worth_not_forgetting">7. One finding from here worth not forgetting</h2>
+<p>Multi-client access <strong>follows the endpoint, not the API</strong>. Two WinMM clients on
+the same BLOOP input both work and <strong>both receive every message</strong>. The <em>GS
+Wavetable Synth</em>, which belongs to the classic <code>wdmaud</code> stack, refuses the second
+open with <em>&quot;The specified device is already in use.&quot;</em> So on one machine, through
+one API, shareable ports and exclusive ports coexist.</p></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>

data/doc/file_list.html ADDED Viewed

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html >
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta charset="utf-8">
+      <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen">
+      <link rel="stylesheet" href="css/common.css" type="text/css" media="screen">
+      <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+      <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
+    <title>File List</title>
+    <base id="base_target" target="_parent">
+  </head>
+  <body>
+    <div id="content">
+      <div class="fixed_header">
+        <h1 id="full_list_header">File List</h1>
+        <div id="full_list_nav">
+            <span><a target="_self" href="class_list.html">
+              Classes
+            </a></span>
+            <span><a target="_self" href="method_list.html">
+              Methods
+            </a></span>
+            <span><a target="_self" href="file_list.html">
+              Files
+            </a></span>
+        </div>
+        <div id="search">
+          <label for="search-class">Search:</label>
+          <input id="search-class" type="text">
+        </div>
+      </div>
+      <ul id="full_list" class="file">
+  <li id="object_README" class="odd">
+    <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
+  </li>
+  <li id="object_testing-on-windows" class="even">
+    <div class="item"><span class="object_link"><a href="file.testing-on-windows.html" title="testing-on-windows">testing-on-windows</a></span></div>
+  </li>
+      </ul>
+    </div>
+  </body>
+</html>

data/doc/frames.html ADDED Viewed

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+	<title>MIDI Communications Windows API</title>
+</head>
+<script type="text/javascript">
+var mainUrl = 'index.html';
+try {
+    var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
+    var name = match ? match[1] : mainUrl;
+    var url = new URL(name, location.href);
+    window.top.location.replace(url.origin === location.origin ? name : mainUrl);
+} catch (e) {
+    window.top.location.replace(mainUrl);
+}
+</script>
+<noscript>
+  <h1>Oops!</h1>
+  <h2>YARD requires JavaScript!</h2>
+</noscript>
+</html>