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/index.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="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</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>