OpenLamp Beat Sync — 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.

This package does no MIDI control — despite the PyPI name, which is kept for continuity. It follows a tempo source (Ableton Link or MIDI clock) and drives the engine's local HTTP API. Notes → colours, CC → brightness and Program Change → presets live in the engine's midi.py. See Scope.

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.

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-python → midi.py, the reference implementation of the OpenLamp MIDI convention. (Before v0.2.0 this package also shipped a separate MIDI bridge; it was removed — use the engine's midi.py.)

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

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.

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 OpenLamp 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.