openlamp-midi — Ableton Link / tempo for OpenLamp lamps

Flash your OpenLamp lamps on the beat, phase-accurate, from an Ableton Link session or a MIDI clock. 100 % local.

pip install "openlamp-midi[link]"          # [link] adds Ableton Link (native build)
python3 beatsync.py --source link --action pulse --accent

beatsync.py follows the tempo source and drives the lamps via the engine's local API — pulsing on the beat, with latency anticipation (fires early so the light lands on the beat) and an accent on the downbeat (exact under Link, which shares the bar's phase). See --help for --source link | taplink | clock | tap.

Scope

This package is only the tempo/beat layer. The MIDI control path — notes → colours, CC → brightness/effects, Program Change → presets — moved into the engine and now lives in openlamp/engine → midi.py, the reference implementation of the wled-midi convention. (Before v0.2.0 this package also shipped a separate MIDI bridge; it was removed — use the engine's midi.py.)

Family

Layer	Repo	Role
convention	wled-midi	the MIDI↔WLED spec
engine	engine	drives the lamps + implements the convention (midi.py)
Ableton	live	Ableton Live frontend
tempo	this repo	Ableton Link / MIDI-clock beat pulse

Uses the engine's local API (127.0.0.1:8377). Requires the engine running.

Architecture & the Ableton Link / GPL boundary

OpenLamp is split so that the one component touching Ableton Link is a small, separate, auditable process — everything else is a separate program reached only over a local HTTP API. This keeps the GPL reach of Link/aalink confined to a single place.

How the pieces are wired

• This package (openlamp-midi / beatsync.py) runs as its own process. It is a standalone CLI helper, launched independently — not embedded in, nor spawned by, the engine.
• It talks to the engine only over the local HTTP API on 127.0.0.1:8377 (plain urllib requests to /cmd and /status). There is no in-process call, FFI, shared memory, or linking between the two — the engine owns the persistent device connections; this helper only POSTs commands to it.
• Ableton Link is reached via aalink and is imported only here — a lazy, local from aalink import Link inside the Link source, gated behind the optional extra: pip install "openlamp-midi[link]". The engine and the frontends contain zero Link/aalink references.

What that means for licensing

Ableton Link is GPLv2-or-later, and aalink (its Python binding, installed by the [link] extra) is GPLv3 — a component that loads them in the same process forms a combined program governed by the GPL (GPLv3). In OpenLamp:

• The only process that ever combines with aalink is beatsync.py (this package). It is MIT; since MIT is one-way compatible with the GPL, combining it with Link at runtime is fine and the effective combined program honors the GPL.
• The engine is a genuinely separate program that communicates only over the local HTTP API and carries no Link code, so it stays under its own (permissive) license — the GPL obligation does not propagate to it.
• The frontends (Stream Deck plugin, etc.) likewise reach the engine only over that same local HTTP API and never combine with Link, so the GPL never reaches them.

Invariant: GPL (via aalink/Link) is confined to one process — beatsync.py. Every other OpenLamp component is a separate program reached only over local HTTP, so the GPL obligation never reaches the engine or the frontends.

Installing the [link] extra pulls in aalink (GPLv3), which incorporates Ableton Link (GPLv2-or-later); the resulting combined program (this helper + aalink + Link) is therefore governed by GPLv3. Without the extra, openlamp-midi is a pure-Python MIT package that does not touch Link at all.

Commercial / proprietary bundling: if you distribute beatsync.py commercially — e.g. bundled inside a closed, proprietary application — a commercial Ableton Link license is required (Link is dual-licensed GPL / commercial). Open-source and personal use are covered by the GPL path above.

This boundary was reviewed with the Ableton Link team (July 2026), who confirmed the separation is sound and recommended these notices.

License

MIT — for this package's own source (beatsync.py).

Optional dependency: the [link] extra installs aalink (GPLv3, a Python binding to Ableton Link, which is GPLv2-or-later). When you install that extra, the running combination is governed by GPLv3 as described above; commercial / proprietary bundling additionally requires a commercial Ableton Link license. The MIT license covers this repository's own code; it does not relicense aalink or Link.

---

Two open standards, one bridge. This implements the open wled-midi convention — the agreed dictionary between MIDI (the MIDI Association) and WLED. Free for anyone to build on: see the convention's openness & patent policy (§14) and the licensing note. Part of OpenLamp.