UniPad - Play Rhythm

The keyLED folder stores LED animation files. Each file defines a LED sequence that plays when a specific button is pressed.

File Naming Convention

The file name itself contains the mapping information, separated by spaces.

chain x y [loop]

Field	Description
`chain`	Chain number (1 ~ chain)
`x`	Button X coordinate (1 ~ buttonX)
`y`	Button Y coordinate (1 ~ buttonY)
`loop`	Repeat count (default: 1, `0` = infinite loop)

Example File Names

keyLED/
├── 1 1 1          → Chain 1, (1,1), play once
├── 1 1 1 0        → Chain 1, (1,1), infinite loop
├── 1 2 3 2        → Chain 1, (2,3), repeat 2 times
└── 2 1 1          → Chain 2, (1,1), play once

Mapping multiple files to the same coordinate creates a circular queue, just like keySound.

Files queue by name after NFC normalization and lower-casing, compared by UTF-16 code units. Composed and decomposed spellings therefore give the same order. The original file names are used to open the files.

Event Syntax

Write LED events one per line inside the file. Fields are separated by spaces. The text encoding follows the same rules as keySound.

`on` — Turn LED On

on x y color [velocity]
on x y auto velocity

Shorthand: o

Field	Description
`x`	LED X coordinate, `*` / `mc` (chain round LED), or `l` (logo LED)
`y`	LED Y coordinate. For `l`, leave it out or put a placeholder such as `0` in its place, but not `a` or `auto` (see Special Coordinates)
`color`	6-digit HEX color (e.g., `FF0000`) or `auto` / `a`
`velocity`	MIDI velocity (0~127), required when using `auto`

Color Specification

Format	Example	Behavior
HEX only	`on 1 1 FF0000`	Displays red in the app
HEX + velocity	`on 1 1 FF0000 5`	Red in app, sends velocity 5 to Launchpad
auto + velocity	`on 1 1 auto 72`	Uses Launchpad palette color mapped to velocity 72

Special Coordinates

Token Meaning

* or mc Round (chain) LEDs on Launchpad top/sides

l Logo LED. y can be left out: on l FF0000, on l auto 72, off l. Or a placeholder such as 0 can stand in the y position: on l 0 FF0000, on l 0 FF0000 5, on l 0 auto 72. Do not use a or auto as the placeholder: on l a FF0000 is read as the auto color with velocity FF0000, and the line is dropped. To send a velocity with a HEX color, keep a value in the y position: without it, on l FF0000 5 reads 5 as the color (000005, almost black).

Token	Meaning
`*` or `mc`	Round (chain) LEDs on Launchpad top/sides
`l`	Logo LED. `y` can be left out: `on l FF0000`, `on l auto 72`, `off l`. Or a placeholder such as `0` can stand in the `y` position: `on l 0 FF0000`, `on l 0 FF0000 5`, `on l 0 auto 72`. Do not use `a` or `auto` as the placeholder: `on l a FF0000` is read as the auto color with velocity `FF0000`, and the line is dropped. To send a velocity with a HEX color, keep a value in the `y` position: without it, `on l FF0000 5` reads `5` as the color (`000005`, almost black).

`off` — Turn LED Off

off x y

Shorthand: f. You can use * / mc or l for the x position.

`delay` — Wait

delay ms

Shorthand: d. Waits the specified milliseconds before the next event. delay 0 does not wait.

`chain` — Switch Chain

chain chainNumber

Shorthand: c. Switches chains during LED sequence execution. If the pack has no such chain, the nearest one is used (chain 1 or the last chain).

Full Example

File name: 1 3 2 0 (Chain 1, coordinate (3,2), infinite loop)

on 3 2 FF0000
on 3 3 00B8D4
delay 100
off 3 2
off 3 3
delay 50
on * 1 auto 72
delay 100
off * 1

Playback

Releasing the button stops an endless (loop 0) animation at once and turns off the LEDs it lit.
An animation that plays once or N times keeps running to its end after the button is released.
Pressing the same button again while its animation runs turns off that animation's LEDs and starts the next animation of the button from the beginning.

Validation

Files with out-of-range coordinates in the file name are ignored.
The on command requires either color (4 tokens) or auto + velocity (5 tokens). A logo line (l) without y is the exception: on l FF0000 (3 tokens) and on l auto 72 (4 tokens) are valid.
Unrecognized commands are skipped.
An on or off line whose coordinates are outside the pad grid (0, negative, or greater than buttonX / buttonY) is kept without a warning and skipped when the animation plays; the other lines of the file still play.
A warning is logged if loop is negative.

Colour and release details

Colours use one to six ASCII hex digits. A bare a, with no following velocity, means hex 00000A (almost black), including on l a and on * 1 a. It does not mean an incomplete auto-colour command. In on l a FF0000, a does select auto colour and FF0000 is an invalid velocity; for a logo HEX colour use on l FF0000 or on l 0 FF0000. A HEX-only colour sends velocity 4 to the Launchpad; the device colour can differ from the app's RGB colour. A wrong column count produces a format warning before round-light index range is checked (including o mc 99). Android and web are being aligned on that warning order. Releasing an endless animation follows its original press after a chain change. When several player inputs press one pad, each release ends only the animation that input started; manual and auto-play input own their animations separately. App updates are aligning release ownership.

keyLED/