| Name | lunchkey JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Control Novation Launchkey MIDI keyboard with LED animations and MIDI functionality |
| upload_time | 2025-08-24 09:51:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
midi
novation
launchkey
music
led
controller
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# lunchkey
Control Novation Launchkey MIDI keyboard with LED animations and MIDI functionality.
## Description
`lunchkey` is a Python library and command-line tool for controlling Novation Launchkey MIDI keyboards. It provides functionality to:
- Connect to Launchkey devices via MIDI
- Control LED lights on the keyboard
- Run animated LED patterns
- Switch between Basic and InControl modes
- Automatically detect Launchkey models (MK1, MK2, MK3)
## Features
- **MIDI Integration**: Uses `mido` and `python-rtmidi` for robust MIDI communication
- **LED Control**: Full control over all 18 LED lights (9 per row)
- **Animation System**: Built-in LED sweep animation with customizable colors
- **Model Detection**: Automatic detection of Launchkey model for proper MIDI channel usage
- **Port Management**: Smart MIDI port connection with fallback strategies
- **Command Line Interface**: Easy-to-use CLI for quick testing and control
## Requirements
- Python 3.10 or higher
- Novation Launchkey MIDI keyboard (MK1, MK2, or MK3)
- MIDI drivers installed on your system
## Installation
### Using uv (Recommended)
[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver.
1. **Install uv** (if not already installed):
```bash
# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Clone and install the project**:
```bash
git clone https://github.com/aminya/lunchkey.git
cd lunchkey
uv sync
```
3. **Run Python scripts directly with uv**:
```bash
# Run the main script
uv run python -m lunchkey.main
# Or activate the virtual environment for interactive use
uv shell
```
## Usage
### Command Line Interface
The main script provides several command-line options:
```bash
# List available MIDI ports
uv run python -m lunchkey.main --list-ports
# Connect to a specific MIDI port
uv run python -m lunchkey.main --port "MIDIOUT2"
# Connect without running animation (useful for testing)
uv run python -m lunchkey.main --port "MIDIOUT2" --no-animation
# Use default port (MIDIOUT2)
uv run python -m lunchkey.main
```
### Python API
```python
from mido.backends.backend import Backend
from lunchkey.main import Launchkey
# Initialize and connect
backend = Backend(name="mido.backends.rtmidi", load=True)
launchkey = Launchkey(backend)
# Connect to MIDI port
launchkey.connect_midi_output("MIDIOUT2")
# Detect model and enable InControl mode
launchkey.detect_launchkey_model()
launchkey.set_incontrol_mode(True)
# Control individual LEDs
launchkey.write_led(96, 127) # Turn on first LED with full brightness
# Turn off all LEDs
launchkey.turn_off_all_leds()
# Clean up
launchkey.close()
```
## MIDI Port Configuration
The tool automatically tries to connect to MIDI ports in this order:
1. **Direct connection**: Uses the specified port name/index
2. **Pattern matching**: Searches for ports containing the specified name
3. **Fallback**: Attempts to connect to port index 0
Common MIDI port names for Launchkey devices:
- `MIDIOUT2` (Windows)
- `Launchkey MK3` (macOS/Linux)
- `Launchkey MK2` (macOS/Linux)
## Launchkey Models
The tool automatically detects your Launchkey model:
- **MK1**: Uses MIDI channel 0 for InControl mode
- **MK2/MK3**: Uses MIDI channel 15 for InControl mode
## LED Layout
The Launchkey has 18 LEDs arranged in two rows:
- **Row 1**: Notes 96-104 (9 LEDs)
- **Row 2**: Notes 112-120 (9 LEDs)
LED colors are controlled via velocity values (0-127), with specific ranges for different colors.
## Development
### Project Structure
```
lunchkey/
├── lunchkey/
│ └── main.py # Main implementation
├── pyproject.toml # Project configuration
├── uv.lock # Dependency lock file
└── README.md # This file
```
### Dependencies
- `mido>=1.3.3`: MIDI library for Python
- `python-rtmidi>=1.5.8`: Real-time MIDI backend
### Running Tests
```bash
# Run tests directly with uv (recommended)
uv run pytest
# Or activate virtual environment first
uv shell
pytest
```
## Troubleshooting
### Common Issues
1. **"No MIDI ports found"**
- Ensure MIDI drivers are installed
- Check that your Launchkey is connected and powered on
- Try running `--list-ports` to see available ports
2. **"Failed to open port"**
- Verify the port name with `--list-ports`
- Ensure no other applications are using the MIDI port
- Try using port index instead of name
3. **LEDs not responding**
- Check that InControl mode is enabled
- Verify MIDI channel settings for your Launchkey model
- Ensure the device is in the correct mode
### MIDI Setup
- **Windows**: Install Novation USB MIDI drivers
- **macOS**: Use built-in Core MIDI support
- **Linux**: Install `timidity` or similar MIDI utilities
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the terms specified in the LICENSE file.
## Acknowledgments
- Novation for the Launchkey hardware and the [programmer's guide](https://www.novationmusic.com/en/support/downloads/launchkey-mk2-mk3-programmers-guide)
- The `mido` and `python-rtmidi` projects for MIDI functionality
Raw data
{
"_id": null,
"home_page": null,
"name": "lunchkey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "midi, novation, launchkey, music, led, controller",
"author": null,
"author_email": "Amin Yara <amin.yara@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a9/dc/004e4dc6cfdee8d2e8a282a8f1975aa59852327c92153d5ac127fa48f261/lunchkey-0.1.0.tar.gz",
"platform": null,
"description": "# lunchkey\r\n\r\nControl Novation Launchkey MIDI keyboard with LED animations and MIDI functionality.\r\n\r\n\r\n\r\n## Description\r\n\r\n`lunchkey` is a Python library and command-line tool for controlling Novation Launchkey MIDI keyboards. It provides functionality to:\r\n\r\n- Connect to Launchkey devices via MIDI\r\n- Control LED lights on the keyboard\r\n- Run animated LED patterns\r\n- Switch between Basic and InControl modes\r\n- Automatically detect Launchkey models (MK1, MK2, MK3)\r\n\r\n## Features\r\n\r\n- **MIDI Integration**: Uses `mido` and `python-rtmidi` for robust MIDI communication\r\n- **LED Control**: Full control over all 18 LED lights (9 per row)\r\n- **Animation System**: Built-in LED sweep animation with customizable colors\r\n- **Model Detection**: Automatic detection of Launchkey model for proper MIDI channel usage\r\n- **Port Management**: Smart MIDI port connection with fallback strategies\r\n- **Command Line Interface**: Easy-to-use CLI for quick testing and control\r\n\r\n## Requirements\r\n\r\n- Python 3.10 or higher\r\n- Novation Launchkey MIDI keyboard (MK1, MK2, or MK3)\r\n- MIDI drivers installed on your system\r\n\r\n## Installation\r\n\r\n### Using uv (Recommended)\r\n\r\n[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver.\r\n\r\n1. **Install uv** (if not already installed):\r\n ```bash\r\n # On Windows (PowerShell)\r\n powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\r\n\r\n # On macOS/Linux\r\n curl -LsSf https://astral.sh/uv/install.sh | sh\r\n ```\r\n\r\n2. **Clone and install the project**:\r\n ```bash\r\n git clone https://github.com/aminya/lunchkey.git\r\n cd lunchkey\r\n uv sync\r\n ```\r\n\r\n3. **Run Python scripts directly with uv**:\r\n ```bash\r\n # Run the main script\r\n uv run python -m lunchkey.main\r\n\r\n # Or activate the virtual environment for interactive use\r\n uv shell\r\n ```\r\n## Usage\r\n\r\n### Command Line Interface\r\n\r\nThe main script provides several command-line options:\r\n\r\n```bash\r\n# List available MIDI ports\r\nuv run python -m lunchkey.main --list-ports\r\n\r\n# Connect to a specific MIDI port\r\nuv run python -m lunchkey.main --port \"MIDIOUT2\"\r\n\r\n# Connect without running animation (useful for testing)\r\nuv run python -m lunchkey.main --port \"MIDIOUT2\" --no-animation\r\n\r\n# Use default port (MIDIOUT2)\r\nuv run python -m lunchkey.main\r\n```\r\n\r\n### Python API\r\n\r\n```python\r\nfrom mido.backends.backend import Backend\r\nfrom lunchkey.main import Launchkey\r\n\r\n# Initialize and connect\r\nbackend = Backend(name=\"mido.backends.rtmidi\", load=True)\r\nlaunchkey = Launchkey(backend)\r\n\r\n# Connect to MIDI port\r\nlaunchkey.connect_midi_output(\"MIDIOUT2\")\r\n\r\n# Detect model and enable InControl mode\r\nlaunchkey.detect_launchkey_model()\r\nlaunchkey.set_incontrol_mode(True)\r\n\r\n# Control individual LEDs\r\nlaunchkey.write_led(96, 127) # Turn on first LED with full brightness\r\n\r\n# Turn off all LEDs\r\nlaunchkey.turn_off_all_leds()\r\n\r\n# Clean up\r\nlaunchkey.close()\r\n```\r\n\r\n## MIDI Port Configuration\r\n\r\nThe tool automatically tries to connect to MIDI ports in this order:\r\n\r\n1. **Direct connection**: Uses the specified port name/index\r\n2. **Pattern matching**: Searches for ports containing the specified name\r\n3. **Fallback**: Attempts to connect to port index 0\r\n\r\nCommon MIDI port names for Launchkey devices:\r\n- `MIDIOUT2` (Windows)\r\n- `Launchkey MK3` (macOS/Linux)\r\n- `Launchkey MK2` (macOS/Linux)\r\n\r\n## Launchkey Models\r\n\r\nThe tool automatically detects your Launchkey model:\r\n\r\n- **MK1**: Uses MIDI channel 0 for InControl mode\r\n- **MK2/MK3**: Uses MIDI channel 15 for InControl mode\r\n\r\n## LED Layout\r\n\r\nThe Launchkey has 18 LEDs arranged in two rows:\r\n\r\n- **Row 1**: Notes 96-104 (9 LEDs)\r\n- **Row 2**: Notes 112-120 (9 LEDs)\r\n\r\nLED colors are controlled via velocity values (0-127), with specific ranges for different colors.\r\n\r\n## Development\r\n\r\n### Project Structure\r\n\r\n```\r\nlunchkey/\r\n\u251c\u2500\u2500 lunchkey/\r\n\u2502 \u2514\u2500\u2500 main.py # Main implementation\r\n\u251c\u2500\u2500 pyproject.toml # Project configuration\r\n\u251c\u2500\u2500 uv.lock # Dependency lock file\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n### Dependencies\r\n\r\n- `mido>=1.3.3`: MIDI library for Python\r\n- `python-rtmidi>=1.5.8`: Real-time MIDI backend\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Run tests directly with uv (recommended)\r\nuv run pytest\r\n\r\n# Or activate virtual environment first\r\nuv shell\r\npytest\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **\"No MIDI ports found\"**\r\n - Ensure MIDI drivers are installed\r\n - Check that your Launchkey is connected and powered on\r\n - Try running `--list-ports` to see available ports\r\n\r\n2. **\"Failed to open port\"**\r\n - Verify the port name with `--list-ports`\r\n - Ensure no other applications are using the MIDI port\r\n - Try using port index instead of name\r\n\r\n3. **LEDs not responding**\r\n - Check that InControl mode is enabled\r\n - Verify MIDI channel settings for your Launchkey model\r\n - Ensure the device is in the correct mode\r\n\r\n### MIDI Setup\r\n\r\n- **Windows**: Install Novation USB MIDI drivers\r\n- **macOS**: Use built-in Core MIDI support\r\n- **Linux**: Install `timidity` or similar MIDI utilities\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests if applicable\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nThis project is licensed under the terms specified in the LICENSE file.\r\n\r\n## Acknowledgments\r\n\r\n- Novation for the Launchkey hardware and the [programmer's guide](https://www.novationmusic.com/en/support/downloads/launchkey-mk2-mk3-programmers-guide)\r\n- The `mido` and `python-rtmidi` projects for MIDI functionality\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Control Novation Launchkey MIDI keyboard with LED animations and MIDI functionality",
"version": "0.1.0",
"project_urls": {
"Bug_Reports": "https://github.com/aminya/lunchkey/issues",
"Homepage": "https://github.com/aminya/lunchkey",
"Repository": "https://github.com/aminya/lunchkey"
},
"split_keywords": [
"midi",
" novation",
" launchkey",
" music",
" led",
" controller"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d287c299a692fee80ece74c5600adfeb23fb72c7082e83473d8252b2172fc304",
"md5": "5690fa9e69705c5cfd60ff37b41fb044",
"sha256": "b1ce434a85f8e35713efd7b45c4d19e26ca97d73ab605c304f19e7b6a76a9e55"
},
"downloads": -1,
"filename": "lunchkey-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5690fa9e69705c5cfd60ff37b41fb044",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7883,
"upload_time": "2025-08-24T09:51:08",
"upload_time_iso_8601": "2025-08-24T09:51:08.420138Z",
"url": "https://files.pythonhosted.org/packages/d2/87/c299a692fee80ece74c5600adfeb23fb72c7082e83473d8252b2172fc304/lunchkey-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a9dc004e4dc6cfdee8d2e8a282a8f1975aa59852327c92153d5ac127fa48f261",
"md5": "47a59127a9bf8dbae82e58da305ef5b3",
"sha256": "8c4f91d92e219f36c32a6daa016099a3221bfd096a53cb85cca85654d58c2152"
},
"downloads": -1,
"filename": "lunchkey-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "47a59127a9bf8dbae82e58da305ef5b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7263,
"upload_time": "2025-08-24T09:51:09",
"upload_time_iso_8601": "2025-08-24T09:51:09.406180Z",
"url": "https://files.pythonhosted.org/packages/a9/dc/004e4dc6cfdee8d2e8a282a8f1975aa59852327c92153d5ac127fa48f261/lunchkey-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 09:51:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aminya",
"github_project": "lunchkey",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "lunchkey"
}
