Metadata-Version: 2.4
Name: launchpad-matrix
Version: 0.1.0
Summary: A Python library that treats a Novation Launchpad as a 9x9 addressable button and LED grid
Author-email: Hrach Sarukhanyan <hrach.sarukhanyan@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/hrachhhhh/launchpad-py
Project-URL: Bug Tracker, https://github.com/hrachhhhh/launchpad-py/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: mido
Requires-Dist: python-rtmidi
Dynamic: license-file

# Launchpad.py

A Python library that treats a Novation Launchpad as a 9×9 addressable button and LED grid — built on top of `mido` for MIDI I/O.

Instead of dealing with raw MIDI note numbers and control-change messages, `Launchpad.py` gives you simple (x, y) coordinates to light pads, listen for presses, and handle device orientation — making it easy to build custom visualizations, controllers, or interactive tools on real hardware.

## Features

- **Simple coordinate API** — `Light(x, y, velocity)` instead of raw MIDI notes
- **Input listening** — register a callback and get `(x, y, velocity)` on every button press
- **Grid rotation** — supports all 4 orientations (0°, 90°, 180°, 270°) with correct coordinate transforms, so you can mount or hold the device any way you like
- **Auto-reconnect** — a background watchdog thread detects disconnects and automatically reconnects, so the device coming unplugged doesn't crash your program
- **Clean shutdown** — ports are closed properly on exit via `atexit`

## Installation

```bash
pip install mido python-rtmidi
```

Then just drop `launchpad.py` into your project and import it — no packaging step required yet.

## Quick start

```python
from launchpad import Launchpad
import time

lp = Launchpad()

# Light up a diagonal line
for i in range(8):
    lp.Light(i, i, 60)

time.sleep(2)

# Listen for button presses and light them up on press
def on_press(x, y, velocity):
    print(f"Pressed: ({x}, {y})")
    lp.Light(x, y, velocity)

lp.start_listening(on_press)

try:
    while True:
        time.sleep(0.1)
except KeyboardInterrupt:
    lp.cleanup()
```

See [`example.py`](example.py) for a complete runnable demo.

## API reference

| Method | Description |
|---|---|
| `Light(x, y, velocity)` | Lights the pad at `(x, y)` (0–8 range, includes side/top control buttons) with the given velocity (0–127, where 0 turns it off) |
| `Rotate(rotation)` | Sets grid orientation: `0`, `1`, `2`, or `3` (90° increments) |
| `start_listening(callback)` | Starts listening for button presses; calls `callback(x, y, velocity)` on each press |
| `stop_listening()` | Stops the input listener |
| `cleanup()` | Closes MIDI ports safely |

## Requirements

- A Novation Launchpad (developed and tested on Launchpad S)
- Python 3.x
- `mido` and a MIDI backend (`python-rtmidi` recommended)

## Notes

This was built as a personal project to interface a Launchpad with flight simulator controls via SimConnect, but the library itself is general-purpose — usable for any project that wants a simple grid-based interface to a Launchpad.


## License

MIT License

Copyright (c) 2026 Hrach Sarukhanyan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION_ OF AN CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
