Metadata-Version: 2.4
Name: launchkey-lights
Version: 0.1.0
Summary: Control the pad LEDs on a Novation Launchkey Mini MK4
License: MIT
Requires-Python: >=3.9
Requires-Dist: mido
Requires-Dist: python-osc
Requires-Dist: python-rtmidi
Description-Content-Type: text/markdown

# launchkey-lights
Control the pad LEDs on a Novation Launchkey Mini MK4 programmatically.

This is unreviewed AI-generated code.

## Motivation
I want to make a small drum machine using a launchkey mk4. This involves controlling lighting; I decided to separate this into a separate program for modularity and to make debugging different.

I may generalise this daemon to other devices, or use the same protocol for other daemons specialised for interfaces.

## Alternatives and prior work
There do not seem to be that many midi devices which have programmable control over their pad's light settings. Some Akai devices support this. Novation Launchpad devices support this. The cheapest device is likely an old launchpad mini. I bought a launchkey device because I wanted a device immediately and already owned launchpad devices which were in another location. The launchkey trades off fewer pads for the presence of encoders and keys and pressure sensitivity of pads.

You could directly use the MIDI messages to control the lights yourself but this might impair readability in your code. The values here are taken from Novation's Launchkey **MK3** Programmer's Reference, and confirmed working on MK4 hardware: the DAW mode handshake, the pad note numbers and the colour palette all carried over unchanged.

## How it works
Two things are needed before a pad will light:

1. LED commands go to the device's **second** port, the "DAW" port, not the
   port the keys and pads send on.
2. The device must be put into **DAW mode** first, with a handshake. Without
   it the DAW port ignores LED commands.

Once in DAW mode, a pad is lit by sending a note-on to its note number, with
the velocity selecting a color from a palette. The *channel* selects the
lighting style rather than any sound: static, flashing or pulsing.

## Usage

    launchkey-lights ports              # list MIDI ports
    launchkey-lights on 0               # light the first pad
    launchkey-lights on 0 --color 21
    launchkey-lights on 0 --style pulsing
    launchkey-lights off 0

If nothing lights up, the note numbers are probably wrong. Find them:

    launchkey-lights probe --start 96 --end 111

which lights each note in turn and prints it, so you can watch the device and
see which range corresponds to the pads.

## OSC support
OSC is a message protocol from the computer music world. It is not an extension of MIDI and shares no wire format with it, but it does support string arguments, variable length argument lists, and hierarchical addresses with pattern matching.

`launchkey-lights` can run as a daemon which receives OSC messages to update lighting. I wrote this so that I could control lighting from a separate drum machine program.

    launchkey-lights daemon                     # TCP on 127.0.0.1:9000
    launchkey-lights daemon --transport udp     # what more music tools speak

    /launchkey/pad/<n>/color   s|i        name or palette index
    /launchkey/pad/<n>/style   s          static | flashing | pulsing
    /launchkey/grid            16 x s|i   whole grid, row major
    /launchkey/rect            x y w h, then w*h colours
    /launchkey/all/color       s|i

Pads are registered individually, so client side patterns match: `/launchkey/pad/*/color`.

### Grids
The pads are a 2x8 grid numbered 0-15 in reading order. `/launchkey/grid` takes sixteen colours; `/launchkey/rect` takes x, y, width, height and then width*height colours, to update part of the grid without disturbing the rest. Colours can be separate arguments or one whitespace separated string:

    /launchkey/grid "red orange yellow lime green cyan blue violet off off off off off off off off"

## Installation

    pipx install launchkey-lights
