Skip to main content

lyte

lyte is a Python 3.13 lighting player for Twinkly and WLED pixel strings and DMX instruments over Art-Net. One installation can play uFor scores on multiple pixel outputs while driving DMX fixtures. uFor score libraries own light layouts, animation settings, composition, and scalar controls. lyte provides NumPy effect rendering, MIDI control, local rehearsal, and installation playback.

Pixel animations render C-contiguous numpy.float32 RGB frames. Conversion to Twinkly's byte format happens at the output boundary. DMX instruments use typed channel categories and render independent 512-slot universe frames.

Twinkly Commands

Inspect the discovered device without changing it, prepare and play a uFor score, or list scores that can be rendered to HTML:

lyte diagnostic
lyte animate examples:/composition.toml --library-config examples/library.toml
lyte preview --library-config examples/library.toml

Override exported scalar controls as name/value pairs, for example --parameters brightness 0.5.

Generate a hardware-free preview from the same score:

lyte preview examples:/composition.toml --output preview.html --library-config examples/library.toml

Render browser- and desktop-playable MP4 files from selected scores, or omit the selectors to render every animation score in the library:

lyte render examples:/composition.toml examples:/aurora.toml \
  --library-config examples/library.toml --output movies
lyte render --library-config examples/library.toml --output movies

lyte render lays out LEDs in a grid. --diameter, --padding, --shape, --layout COLUMNS ROWS, and --background-color control the movie image. It requires ffmpeg on PATH and writes one H.264 MP4 per score.

Direct Twinkly playback discovers a single device when no host is supplied. It authenticates the device, enters realtime mode, probes the HTTP connection while streaming UDP frames, recovers after connection failures, and requests blackout when playback ends.

uFor Scores and Compositions

Register score roots in a uFor library configuration, then select a score by literal library, name, tag, or address. The default configuration is ~/.config/ufor/library.toml; --library-config replaces that default. Reading a library never creates files. List one effect family with:

lyte preview --library-config examples/library.toml --family fields

uFor compositions provide named placement, weighted mixes, crossfades, reversal, gain, component mapping, and timed cues. The score declares its logical update rate, light components, and one-, two-, or three-dimensional layout. Preview uses those authored coordinates. Wiring is a final physical permutation and is never applied to previews or intermediate parts.

The same 250-light graph can be validated, previewed, or played:

lyte validate examples:/composition.toml --library-config examples/library.toml
lyte preview examples:/composition.toml --output preview.html --library-config examples/library.toml
lyte animate examples:/composition.toml --library-config examples/library.toml --duration 10

The example library is rooted at examples/scores/. Its composition places two 125-light ripple parts into named halves, reverses one half, and cues the result against a 250-light aurora. uFor resolves references and presets before lyte prepares one state per part path. No score data contains a Python import path.

Wearable Patches

The supplied wearable catalogue is authored for 250 LEDs split into five logical regions. Its physical map is guessed, not measured:

lyte patch list
lyte patch locator
lyte patch play PATCH_NAME

lyte warns when using the guessed map. If the connected string has a different LED count, it warns again and scales the logical regions and physical map to the actual count. Mark the map as measured only after checking every region on the assembled garment.

The same 36-patch catalogue is available through uFor selectors and the installation runner. patches/wearable-library.toml registers the presets, and patches/wearable-installation.toml configures the single wearable string and shared MIDI controls:

lyte validate wearable:/prism_limbs.toml \
  --library-config patches/wearable-library.toml
lyte installation run patches/wearable-installation.toml

The uFor adapter preserves the legacy algorithms and guessed physical map. The wearable hardware is not currently available, so this path has automated rendering coverage but still requires a physical mapping and MIDI check before performance use.

Installations

lyte installation discovers named Twinkly strings, connects configured WLED targets, and sends DMX through an Art-Net gateway. It starts selectable bound uFor animations in the foreground or as the normal lyte per-user service:

cp examples/installation.toml installation.toml
lyte installation run installation.toml --duration 10
lyte installation install installation.toml
lyte installation status

Each [twinkly] entry is a case-insensitive gestalt selector, such as { product_name = "Dots" }; the empty selector is useful for the one remaining device. No address, MAC, or LED count is configured. [animations.NAME] maps score output names to string expressions: left + right treats two strings as one long strip, and left * right mirrors one rendered frame to both strings. The reccy RPC command select_animation queues a declared animation for the next frame boundary. status reports the active and queued animation plus per-string connection, count, frame, and failure status. The same endpoint supports test, blackout, and stop.

An optional [midi] table enables MIDI input and reconnection. An animation may set activation = "note" and map gate, note, velocity, CC 2 breath, or pitch_bend into public uFor score parameters:

[[animations.reactive.controls]]
source = "breath"
parameter = "brightness"
output = [0.0, 1.0]

velocity and breath are normalized to 0 through 1, and pitch_bend to -1 through 1. output linearly maps that range. A note control can instead use values = [...] as a cyclic lookup table. Program changes select the next configured animation.

The installation's library_config is resolved relative to its TOML file. lyte validates every selected score output before opening hardware. It discovers the actual LED count for each string and scales at output time, logging any authored-layout mismatch. startup_timeout bounds discovery and identification; setup_timeout separately bounds Twinkly authentication and entry into realtime mode across all outputs. Both default to 30 seconds. A stop request interrupts retries after the service starts. Shutdown attempts blackout on every opened output and logs failures; a successful UDP send does not confirm physical output.

lyte validate performs uFor selection and renderer preflight without connecting to hardware or running an installation. For installation-specific software checks, use lyte rehearse with simulated Twinkly LED counts. See doc/guide.md for mixed pixel and DMX configuration.

Documentation

  • doc/guide.md explains the current system, its commands, output boundaries, and hardware validation limits.
  • doc/handover.md records the current handover state.

Metadata

Release files for lyte 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lyte 0.2.0
File Size Uploaded Provenance Actions
lyte-0.2.0.tar.gz 213.8 kB Without provenance Details for lyte-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lyte 0.2.0
File Interpreter ABI Platform Actions
lyte-0.2.0-py3-none-any.whl Python 3 none any Details for lyte-0.2.0-py3-none-any.whl

Total release size: 406.9 kB

Release files / lyte-0.2.0.tar.gz

Download URL lyte-0.2.0.tar.gz
Size 213.8 kB
Tags Source
SHA-256 checksum
How to use checksums
8fe5382a0cec36ed196f5a82e807b6e11872e6cdecf19b63f1c0fe988fe6b946
BLAKE2b-256 checksum
How to use checksums
5a8261167c5c63357eb693261b82c5c05f8448a4484325229dec663415bb95ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / lyte-0.2.0-py3-none-any.whl

Download URL lyte-0.2.0-py3-none-any.whl
Size 193.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28094897e865c4e98482d2bf426f7e0786a4d014135fab26b0923bbbeec1a171
BLAKE2b-256 checksum
How to use checksums
7c37373f3c1e66fd5f30f353c17bf6b600082f005487d6a89d559e326fab9ebc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for lyte 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page