pyMIDIspy 1.0.0__cp314-cp314-macosx_10_13_universal2.whl

pymidispy-1.0.0.dist-info/METADATA

@@ -0,0 +1,436 @@
+Metadata-Version: 2.4
+Name: pyMIDIspy
+Version: 1.0.0
+Summary: Python wrapper for SnoizeMIDISpy - capture outgoing MIDI on macOS
+Home-page: https://github.com/gramster/pyMIDIspy
+Author: gramster
+License: BSD-3-Clause
+Project-URL: Repository, https://github.com/gramster/pyMIDIspy
+Project-URL: Homepage, https://github.com/gramster/pyMIDIspy
+Keywords: midi,macos,coremidi,audio,music
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyobjc-core
+Requires-Dist: pyobjc-framework-Cocoa
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# pyMIDIspy - Python MIDI Spy for macOS
+
+A Python library for MIDI capture on macOS, providing both:
+- **Outgoing MIDI capture** - Spy on MIDI being sent TO destinations (via SnoizeMIDISpy)
+- **Incoming MIDI capture** - Receive MIDI FROM sources (via standard CoreMIDI)
+
+## Overview
+
+This library enables Python applications to:
+
+1. **Capture outgoing MIDI** (`MIDIOutputClient`) - Capture what other applications are *sending* to MIDI outputs. This uses the SnoizeMIDISpy driver and is not possible with normal MIDI APIs.
+
+2. **Receive incoming MIDI** (`MIDIInputClient`) - Standard MIDI input from sources like keyboards and controllers.
+
+Use cases:
+- Debugging MIDI communication between apps and hardware
+- Recording/logging MIDI output from DAWs and other applications  
+- Building MIDI monitoring and analysis tools
+- Capturing both input and output for complete MIDI logging
+
+## Requirements
+
+- **macOS only** - Uses macOS-specific CoreMIDI
+- **Python 3.8+**
+- **Xcode** - Required to build the SnoizeMIDISpy framework from source
+- **PyObjC** (installed automatically) - Required for Objective-C block callbacks
+
+## Installation
+
+### From Source (Recommended)
+
+Clone the repository with submodules and build:
+
+```bash
+git clone --recursive https://github.com/gramster/pyMIDIspy.git
+cd pyMIDIspy
+
+# Build the framework and install the package
+./build.sh
+
+# Or install in development mode
+pip install -e .
+```
+
+### From Wheel (if available)
+
+```bash
+pip install pyMIDIspy
+```
+
+Note: The wheel includes the pre-built SnoizeMIDISpy framework, so no Xcode is required.
+
+### Manual Build
+
+If you need more control over the build process:
+
+```bash
+# 1. Clone with submodules
+git clone --recursive https://github.com/gramster/pyMIDIspy.git
+cd pyMIDIspy
+
+# 2. Initialize submodules if you didn't use --recursive
+git submodule update --init --recursive
+
+# 3. Build using pip (this compiles the framework automatically)
+pip install .
+
+# Or build a wheel
+python -m build
+```
+
+## Quick Start
+
+### Install the MIDI Spy Driver (First Time Only)
+
+The spy driver needs to be installed once to enable outgoing MIDI capture:
+
+```python
+from pyMIDIspy import install_driver_if_necessary
+
+# This installs the driver to ~/Library/Audio/MIDI Drivers/
+error = install_driver_if_necessary()
+if error:
+    print(f"Driver installation failed: {error}")
+else:
+    print("Driver installed successfully!")
+```
+
+**Note:** You may need to restart any running MIDI applications after driver installation.
+
+## Usage
+
+### Incoming MIDI (from sources)
+
+```python
+from pyMIDIspy import MIDIInputClient, get_sources
+
+def on_midi(messages, source_id):
+    for msg in messages:
+        print(f"Received: {msg.data.hex()}")
+
+# List sources
+for src in get_sources():
+    print(f"  {src.name} (ID: {src.unique_id})")
+
+# Receive MIDI from a source
+with MIDIInputClient(callback=on_midi) as client:
+    sources = get_sources()
+    if sources:
+        client.connect_source(sources[0])
+        
+        import time
+        while True:
+            time.sleep(0.1)
+```
+
+### Outgoing MIDI (to destinations)
+
+```python
+from pyMIDIspy import MIDIOutputClient, get_destinations, install_driver_if_necessary
+
+# Install the spy driver (first time only)
+install_driver_if_necessary()
+
+def on_midi(messages, dest_id):
+    for msg in messages:
+        print(f"Captured outgoing: {msg.data.hex()}")
+
+# Capture MIDI being sent to a destination
+with MIDIOutputClient(callback=on_midi) as client:
+    destinations = get_destinations()
+    if destinations:
+        client.connect_destination(destinations[0])
+        
+        import time
+        while True:
+            time.sleep(0.1)
+```
+
+### Both directions
+
+```python
+from pyMIDIspy import MIDIOutputClient, MIDIInputClient, get_sources, get_destinations
+
+def on_incoming(messages, source_id):
+    for msg in messages:
+        print(f"IN:  {msg.data.hex()}")
+
+def on_outgoing(messages, dest_id):
+    for msg in messages:
+        print(f"OUT: {msg.data.hex()}")
+
+# Create both clients
+with MIDIInputClient(callback=on_incoming) as input_client, \
+     MIDIOutputClient(callback=on_outgoing) as output_client:
+    
+    # Connect to all sources and destinations
+    for src in get_sources():
+        input_client.connect_source(src)
+    for dest in get_destinations():
+        output_client.connect_destination(dest)
+    
+    import time
+    while True:
+        time.sleep(0.1)
+```
+
+### Filtering Messages
+
+Use `MessageFilter` to filter MIDI messages before they reach your callback:
+
+```python
+from pyMIDIspy import MIDIInputClient, MessageFilter
+
+# Only receive note messages on channel 1
+filter = MessageFilter(types=["note"], channels=[1])
+
+client = MIDIInputClient(callback=on_midi, message_filter=filter)
+```
+
+**Common filtering patterns:**
+
+```python
+# Exclude timing clock and active sensing (common noise)
+filter = MessageFilter(exclude_types=["timing_clock", "active_sensing"])
+
+# Only note on/off messages
+filter = MessageFilter(types=["note"])
+
+# Only control change messages for specific controllers (mod wheel, volume, pan)
+filter = MessageFilter(types=["control_change"], controllers=[1, 7, 10])
+
+# Only messages on channels 1-4
+filter = MessageFilter(channels=[1, 2, 3, 4])
+
+# Combine: notes on channel 1, excluding note-off
+filter = MessageFilter(types=["note_on"], channels=[1])
+```
+
+**Change filter at runtime:**
+
+```python
+client = MIDIInputClient(callback=on_midi)
+client.connect_source(source)
+
+# Later, add filtering
+client.message_filter = MessageFilter(types=["note"])
+
+# Remove filtering
+client.message_filter = None
+```
+
+**Available message types for filtering:**
+
+| Type | Description |
+|------|-------------|
+| `"note_off"` | Note Off messages |
+| `"note_on"` | Note On messages (velocity > 0) |
+| `"note"` | Both Note On and Note Off |
+| `"control_change"` | Control Change (CC) messages |
+| `"program_change"` | Program Change messages |
+| `"pitch_bend"` | Pitch Bend messages |
+| `"poly_pressure"` | Polyphonic Aftertouch |
+| `"channel_pressure"` | Channel Aftertouch |
+| `"sysex"` | System Exclusive messages |
+| `"timing_clock"` | MIDI Clock (0xF8) |
+| `"transport"` | Start, Stop, Continue |
+| `"active_sensing"` | Active Sensing (0xFE) |
+| `"realtime"` | All realtime (clock, transport, active sensing) |
+| `"channel"` | All channel voice messages |
+| `"system"` | All system messages |
+
+### API Reference
+
+#### Functions
+
+##### `get_destinations() -> List[MIDIDestination]`
+Get a list of all MIDI destinations (outputs) available on the system.
+
+##### `get_destination_by_unique_id(unique_id: int) -> Optional[MIDIDestination]`
+Find a specific MIDI destination by its unique identifier.
+
+##### `get_sources() -> List[MIDISource]`
+Get a list of all MIDI sources (inputs) available on the system.
+
+##### `get_source_by_unique_id(unique_id: int) -> Optional[MIDISource]`
+Find a specific MIDI source by its unique identifier.
+
+##### `install_driver_if_necessary() -> Optional[str]`
+Install the MIDI spy driver (for outgoing capture only). Returns `None` on success.
+
+#### Classes
+
+##### `MIDIInputClient`
+
+Receives incoming MIDI from sources (standard CoreMIDI). No driver required.
+
+```python
+client = MIDIInputClient(callback=my_callback, client_name="MyApp", message_filter=filter)
+```
+
+**Methods:**
+- `connect_source(source: MIDISource)` - Start receiving from a source
+- `connect_source_by_id(unique_id: int)` - Connect by unique ID
+- `disconnect_source(source: MIDISource)` - Stop receiving
+- `disconnect_all()` - Disconnect from all sources
+- `close()` - Release all resources
+
+**Properties:**
+- `connected_sources` - List of currently connected sources
+- `message_filter` - Get/set the MessageFilter (or None)
+
+##### `MIDIOutputClient`
+
+Captures outgoing MIDI sent to destinations. Requires the spy driver.
+
+```python
+client = MIDIOutputClient(callback=my_callback, message_filter=filter)
+```
+
+**Methods:**
+- `connect_destination(destination: MIDIDestination)` - Start capturing from a destination
+- `connect_destination_by_id(unique_id: int)` - Connect by unique ID
+- `disconnect_destination(destination: MIDIDestination)` - Stop capturing
+- `disconnect_destination_by_id(unique_id: int)` - Disconnect by unique ID  
+- `disconnect_all()` - Disconnect from all destinations
+- `close()` - Release all resources
+
+**Properties:**
+- `connected_destinations` - List of currently connected destinations
+- `message_filter` - Get/set the MessageFilter (or None)
+
+##### `MessageFilter`
+
+Filters MIDI messages by type, channel, or other criteria.
+
+```python
+filter = MessageFilter(
+    types=["note", "control_change"],  # Include only these types
+    exclude_types=["timing_clock"],    # Exclude these types
+    channels=[1, 2],                   # Include only these channels (1-16)
+    exclude_channels=[10],             # Exclude these channels
+    controllers=[1, 7, 10],            # For CC: only these controller numbers
+    notes=[60, 62, 64],                # For notes: only these note numbers
+)
+```
+
+##### `MIDISource`
+
+Represents a MIDI source endpoint (input).
+
+##### `MIDIDestination`
+
+Represents a MIDI destination endpoint (output).
+
+##### `MIDIMessage`
+
+Represents a captured MIDI message.
+
+**Attributes:**
+- `timestamp: int` - Host time when the message was sent
+- `data: bytes` - Raw MIDI bytes
+
+**Properties:**
+- `status` - The status byte (or None)
+- `channel` - The MIDI channel 0-15 (for channel messages)
+
+#### Exceptions
+
+- `MIDISpyError` - Base exception class
+- `DriverMissingError` - The MIDI spy driver is not installed
+- `DriverCommunicationError` - Failed to communicate with the driver
+- `ConnectionExistsError` - Already connected to this destination
+- `ConnectionNotFoundError` - Not connected to this destination
+
+## How It Works
+
+The SnoizeMIDISpy framework consists of two parts:
+
+1. **MIDI Driver** (`MIDI Monitor.plugin`) - Installed in `~/Library/Audio/MIDI Drivers/`. This is a CoreMIDI driver that intercepts MIDI data sent to destinations.
+
+2. **Client Framework** - Communicates with the driver via Mach messages to receive the captured MIDI data.
+
+When you connect to a destination, the driver starts forwarding copies of all MIDI messages sent to that destination to your callback.
+
+## Troubleshooting
+
+### "Could not find SnoizeMIDISpy.framework"
+Make sure you've built the framework and either:
+- Set `SNOIZE_MIDI_SPY_FRAMEWORK` environment variable
+- Copied the framework to `/Library/Frameworks/` or `~/Library/Frameworks/`
+
+### "MIDI spy driver is missing"
+Call `install_driver_if_necessary()` to install the driver. You may need to restart your DAW or MIDI applications after installation.
+
+### No MIDI messages received
+- Make sure the driver is installed (for outgoing capture)
+- Verify the endpoint exists with `get_destinations()` or `get_sources()`
+- Check that MIDI is actually being sent/received
+- The MIDI Monitor app from MIDIApps can help debug
+
+## Technical Notes
+
+### Why PyObjC is required
+
+CoreMIDI's `MIDIReadBlock` callback is an Objective-C block type:
+```c
+void (^)(const MIDIPacketList *pktlist, void *srcConnRefCon)
+```
+
+Blocks are not simple C function pointers—they're closures with a special memory layout that the runtime can retain/release. The SnoizeMIDISpy framework calls `CFRetain()` on the callback, which would crash with a plain C function pointer. PyObjC's `objc.Block` creates properly-structured blocks that are ABI-compatible with what CoreMIDI and the framework expect.
+
+## Publishing to PyPI
+
+To publish a new version to PyPI:
+
+```bash
+# 1. Build the wheel (this compiles the SnoizeMIDISpy framework)
+./build.sh
+
+# 2. Verify the package metadata and contents
+twine check dist/*
+
+# 3. (Recommended) Test on TestPyPI first
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ pyMIDIspy
+
+# 4. Upload to PyPI
+twine upload dist/*
+```
+
+**Notes:**
+- The wheel is macOS-only and tagged as `macosx_10_13_universal2` (supports both arm64 and x86_64)
+- Source distributions require Xcode to build the framework
+- You'll need a PyPI account and API token (create at https://pypi.org/manage/account/token/)
+- Store your token in `~/.pypirc` or use `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<your-token>`
+
+## License
+
+BSD License - see the LICENSE file.

pymidispy-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pymidispy-1.0.0.data/purelib/pyMIDIspy/__init__.py,sha256=690ac3uHPf26F8jK3c5JcZmH_w4Dv5p2xv6v02Lb1sY,3858
+pymidispy-1.0.0.data/purelib/pyMIDIspy/core.py,sha256=wmltYpceTqUe5dUsbVvS4zJRhm2lnNv6pBH0QeTjRU4,40631
+pymidispy-1.0.0.data/purelib/pyMIDIspy/midi_utils.py,sha256=dF_Gis2jrmX1QUWgHzdFjpDvoLJrWKYi6qm5MnEbC04,14345
+pymidispy-1.0.0.dist-info/licenses/LICENSE,sha256=4yQhIhnuGo-EYYXInCICmz15ZATx_J2MRz7HRyIfn_o,1493
+pymidispy-1.0.0.dist-info/METADATA,sha256=6QxBDF0D0yQAQ0s3dERjeT89If7DQ38qFGK2q6gDfh4,13570
+pymidispy-1.0.0.dist-info/WHEEL,sha256=k270JeYTEi7JZ22OBvUCY4w-JbllBANjHcahvUbWqko,116
+pymidispy-1.0.0.dist-info/top_level.txt,sha256=3d4Gvqdgt9cIf__y4ODCvrYaKx8dWeAJhsxMoD6f13A,10
+pymidispy-1.0.0.dist-info/RECORD,,

pymidispy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: false
+Tag: cp314-cp314-macosx_10_13_universal2
+

pymidispy-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2001-2023, Kurt Revis
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pymidispy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyMIDIspy