pyvmancer 0.1.0__tar.gz

pyvmancer-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

pyvmancer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install ALSA for python-rtmidi
+        # The -dev headers are needed on Pythons with no python-rtmidi wheel (3.13).
+        run: sudo apt-get update && sudo apt-get install -y libasound2t64 libasound2-dev
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[all]"
+          pip install --group dev || pip install black pylint pytest pytest-cov pytest-xdist pyserial pyusb
+      - name: Format check
+        run: black --check .
+      - name: Lint
+        run: pylint pyvmancer tests
+      - name: Test
+        run: pytest

pyvmancer-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyvmancer-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.ruff_cache/
+.mypy_cache/

pyvmancer-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pyvmancer-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: pyvmancer
+Version: 0.1.0
+Summary: Automate the LZX Industries Videomancer over USB MIDI and USB serial
+Author-email: Josh Bailey <josh@overlyspecific.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/anarkiwi/pyvmancer
+Project-URL: Issues, https://github.com/anarkiwi/pyvmancer/issues
+Keywords: lzx,videomancer,midi,video-synthesis,usb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mido>=1.3
+Requires-Dist: python-rtmidi>=1.5
+Requires-Dist: numpy>=1.24
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: usb
+Requires-Dist: pyusb>=1.2; extra == "usb"
+Provides-Extra: all
+Requires-Dist: pyserial>=3.5; extra == "all"
+Requires-Dist: pyusb>=1.2; extra == "all"
+Dynamic: license-file
+
+# pyvmancer
+
+Python library and CLI to automate the [LZX Industries Videomancer](https://lzxindustries.net/products/videomancer) over USB.
+
+Two control paths, usable together or independently:
+
+| Path | Transport | Covers |
+| --- | --- | --- |
+| USB MIDI | ALSA rawmidi or any `mido` backend | 12 parameters (7/14-bit CC), preset recall, note triggers, clock/transport |
+| USB serial | `/dev/ttyACM*` or libusb | programs, presets, modulation operators, video, settings, filesystem |
+
+## Install
+
+```sh
+pip install pyvmancer            # MIDI only
+pip install "pyvmancer[all]"     # adds serial and libusb transports
+```
+
+On Linux the `python-rtmidi` dependency links `libasound.so.2`:
+
+```sh
+sudo apt-get install libasound2t64
+```
+
+## Use
+
+```python
+import pyvmancer as vm
+
+d = vm.Videomancer.open()
+
+d.load_program("Isotherm")
+d.set_named("Posterize", 5)        # native units: Posterize is 0..7
+d.set_named("Mix", 80)             # Mix is 0..100
+d.set_source("Contrast", "free lfo")
+
+d.set_param(1, 0.75)               # or address slots directly, 0.0..1.0
+d.set_param(7, True)               # toggles take bools
+d.trigger(4)                       # note-trigger a modulation operator
+
+d.set_bpm(128)
+d.play()
+d.close()
+```
+
+MIDI only, no serial link needed:
+
+```python
+with vm.open_midi(channel=1) as m:
+    m.set_param(1, 0.5)
+    m.select_preset(3)
+    m.run_clock(120, beats=8)
+```
+
+## CLI
+
+```sh
+vmancer devices                 # discover attached units and their device nodes
+vmancer operators               # list the 25 modulation operators
+vmancer set 1=0.5 7=on          # set parameters over MIDI
+vmancer preset 3                # recall a preset
+vmancer programs                # list installed FPGA programs
+vmancer load Isotherm           # load a program
+vmancer shell modulation status # run any raw shell command
+```
+
+## Permissions
+
+MIDI needs read/write on `/dev/snd/midiC*D*` (usually granted by a desktop ACL);
+serial needs the `dialout` group or an ACL on `/dev/ttyACM*`. See
+[docs/permissions.md](docs/permissions.md).
+
+## Docs
+
+- [docs/protocol.md](docs/protocol.md) — MIDI implementation and the serial command set
+- [docs/permissions.md](docs/permissions.md) — device node access, containers, udev
+- [docs/firmware-notes.md](docs/firmware-notes.md) — observed firmware behaviour and quirks
+
+## Status
+
+Verified against a Videomancer running firmware `1.0.0-rc.37`. Not affiliated with LZX Industries.
+
+## License
+
+Apache-2.0

pyvmancer-0.1.0/README.md

@@ -0,0 +1,85 @@
+# pyvmancer
+
+Python library and CLI to automate the [LZX Industries Videomancer](https://lzxindustries.net/products/videomancer) over USB.
+
+Two control paths, usable together or independently:
+
+| Path | Transport | Covers |
+| --- | --- | --- |
+| USB MIDI | ALSA rawmidi or any `mido` backend | 12 parameters (7/14-bit CC), preset recall, note triggers, clock/transport |
+| USB serial | `/dev/ttyACM*` or libusb | programs, presets, modulation operators, video, settings, filesystem |
+
+## Install
+
+```sh
+pip install pyvmancer            # MIDI only
+pip install "pyvmancer[all]"     # adds serial and libusb transports
+```
+
+On Linux the `python-rtmidi` dependency links `libasound.so.2`:
+
+```sh
+sudo apt-get install libasound2t64
+```
+
+## Use
+
+```python
+import pyvmancer as vm
+
+d = vm.Videomancer.open()
+
+d.load_program("Isotherm")
+d.set_named("Posterize", 5)        # native units: Posterize is 0..7
+d.set_named("Mix", 80)             # Mix is 0..100
+d.set_source("Contrast", "free lfo")
+
+d.set_param(1, 0.75)               # or address slots directly, 0.0..1.0
+d.set_param(7, True)               # toggles take bools
+d.trigger(4)                       # note-trigger a modulation operator
+
+d.set_bpm(128)
+d.play()
+d.close()
+```
+
+MIDI only, no serial link needed:
+
+```python
+with vm.open_midi(channel=1) as m:
+    m.set_param(1, 0.5)
+    m.select_preset(3)
+    m.run_clock(120, beats=8)
+```
+
+## CLI
+
+```sh
+vmancer devices                 # discover attached units and their device nodes
+vmancer operators               # list the 25 modulation operators
+vmancer set 1=0.5 7=on          # set parameters over MIDI
+vmancer preset 3                # recall a preset
+vmancer programs                # list installed FPGA programs
+vmancer load Isotherm           # load a program
+vmancer shell modulation status # run any raw shell command
+```
+
+## Permissions
+
+MIDI needs read/write on `/dev/snd/midiC*D*` (usually granted by a desktop ACL);
+serial needs the `dialout` group or an ACL on `/dev/ttyACM*`. See
+[docs/permissions.md](docs/permissions.md).
+
+## Docs
+
+- [docs/protocol.md](docs/protocol.md) — MIDI implementation and the serial command set
+- [docs/permissions.md](docs/permissions.md) — device node access, containers, udev
+- [docs/firmware-notes.md](docs/firmware-notes.md) — observed firmware behaviour and quirks
+
+## Status
+
+Verified against a Videomancer running firmware `1.0.0-rc.37`. Not affiliated with LZX Industries.
+
+## License
+
+Apache-2.0

pyvmancer-0.1.0/docs/firmware-notes.md

@@ -0,0 +1,84 @@
+# Firmware notes
+
+Observations from a Videomancer running `1.0.0-rc.37`, serial `E464B0605F113625`.
+The published LZX documentation describes a `2.1.0` firmware, and the two differ
+in several places. Always treat `help` and `fs caps` as authoritative.
+
+## `settings export` resets the USB link
+
+Running `settings export` reliably drops the CDC connection mid-reply:
+
+```
+TransportError: read from /dev/ttyACM0 failed: device reports readiness to read
+but returned no data
+```
+
+The device then re-enumerates with a new USB address; the next write on the old
+handle fails with `EIO`. The unit recovers on its own and no state is lost, but
+any open handle must be reopened, and a `/dev/bus/usb` ACL granted to the old
+address is gone.
+
+The reply appears to exceed the shell's response buffer. `pyvmancer` therefore
+does not wrap `settings export`; use `settings get <key_id>` for individual keys.
+
+## Error codes are tagged
+
+Documented codes are 1-10. This firmware returns them as `0x58000000 | n`, so a
+usage error arrives as `1476395010`. `pyvmancer.shell.decode_error_code` strips
+the tag; `ShellError.code` is the decoded value.
+
+## Command set is much larger than documented
+
+`help` reports 64 commands against the ~30 in the published guide. The additions
+that matter for automation are the whole `modulation` group (`status`, `source`,
+`set`, `reset`, `cc-map`, `latch`, `audio status`), `program info`, the `video`
+and `remote` groups, and `settings get`/`set`/`reset`.
+
+## Not every command acknowledges with `ok`
+
+Most commands reply `@<tag>:ok`, but several use a verb of their own. Observed on
+`1.0.0-rc.37`:
+
+| Command | Reply |
+| --- | --- |
+| `remote enable` | `enabled` |
+| `remote disable` | `disabled` |
+| `midi monitor <mode>` | `monitor <mode>` |
+| `log level <level>` | the level, uppercased, e.g. `INFO` |
+| `language` (no argument) | the current locale, e.g. `en_US` |
+
+`transport play/stop/bpm`, `modulation set/source/reset/latch`, `remote write` and
+the preset and filesystem mutations all do reply `ok`.
+
+## `fs read` is capped at 256 bytes
+
+`fs caps` reports `read_max_bytes: 256`. Larger requests fail, so reads must be
+chunked at or below that. `pyvmancer` queries `fs caps` and uses the reported
+limit.
+
+## Modulation knobs need an active source
+
+`modulation set <index> <manual> <time> <space> <slope>` accepts and acknowledges
+all five arguments even when the slot's source is `Disabled`, but `t`/`sp`/`sl`
+in `program state` stay at 512. Assign a source first, then set the knobs.
+
+## Manual value and MIDI are separate
+
+A MIDI CC does not change `m` in `program state`. It contributes to the combined
+`o` output in `modulation status` while leaving the stored manual value alone,
+matching the documented `Manual + Modulation + MIDI` sum. To change the stored
+value, use `modulation set` over serial.
+
+## Program inventory
+
+21 programs on this unit, several of which are not in the published list
+(`Colorbars`, `Passthru`), and some published names are absent (`Fauxtress`,
+`Moire`, `Mycelium`, `Perlin`). `pyvmancer.const.EMBEDDED_PROGRAMS` is a
+convenience list only; call `programs list`.
+
+## MIDI byte counts
+
+`/proc/asound/card*/midi0` Tx counts are lower than the bytes handed to the
+library because the ALSA sequencer applies running-status compression. A
+high-resolution parameter write plus a program change plus a note pair measured
+21 bytes rather than 26.

pyvmancer-0.1.0/docs/permissions.md

@@ -0,0 +1,80 @@
+# Device access and permissions
+
+The Videomancer presents four device nodes. `vmancer devices` reports all of
+them:
+
+```json
+{
+  "serial": "E464B0605F113625",
+  "rawmidi": "/dev/snd/midiC6D0",
+  "tty": "/dev/ttyACM0",
+  "block": "/dev/sdc",
+  "usbfs": "/dev/bus/usb/003/041"
+}
+```
+
+| Node | Used for | Default owner |
+| --- | --- | --- |
+| `/dev/snd/midiC*D*` | USB MIDI | `root:audio`, usually ACL-granted to the desktop user |
+| `/dev/ttyACM*` | serial shell | `root:dialout` |
+| `/dev/bus/usb/*/*` | serial shell over libusb | `root:root`, mode `0664` |
+| `/dev/sd*` | microSD as mass storage | `root:disk` |
+
+## Granting access
+
+Serial normally just needs group membership, which takes effect on next login:
+
+```sh
+sudo usermod -aG dialout "$USER"
+```
+
+For a persistent, group-free rule, install a udev rule that ACLs every interface
+of the device to the seat's active user:
+
+```
+# /etc/udev/rules.d/70-lzx-videomancer.rules
+SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="14db", TAG+="uaccess"
+SUBSYSTEM=="tty", ATTRS{idVendor}=="16d0", ATTRS{idProduct}=="14db", TAG+="uaccess"
+```
+
+```sh
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+## Containers
+
+Passing the device into a container needs the nodes mapped *and* writable by the
+container uid. Mapping `/dev/snd` alone gives you MIDI but not the shell.
+
+```sh
+docker run --device /dev/snd --device /dev/ttyACM0 ...
+```
+
+If `/dev/tty*` cannot be mapped, the serial shell can still be reached through
+libusb against `/dev/bus/usb`, which needs read-write on the usbfs node:
+
+```python
+shell = pyvmancer.open_shell(prefer="usb")
+```
+
+Note that usbfs requires `O_RDWR`; read-only access is not enough to claim the
+interface, and the node's address changes whenever the device re-enumerates.
+
+Where `libasound.so.2` is absent, the pure-Python ALSA rawmidi backend still
+works and needs no ALSA userspace at all:
+
+```python
+midi = pyvmancer.open_midi(prefer="rawmidi")
+```
+
+## Diagnosing
+
+```sh
+vmancer devices                  # what the library can see
+amidi -l                         # ALSA's view of MIDI ports
+cat /proc/asound/card*/midi0     # rawmidi Tx/Rx byte counters
+```
+
+The Tx counter is the quickest confirmation that bytes actually reached the
+device. ALSA applies running-status compression, so the count is usually lower
+than the number of bytes handed to the library.