LightPlayer

LightPlayer is an open platform for LED art: author effects as GLSL shaders in a browser studio, preview them in a built-in simulator, and run them on real hardware — where they are JIT-compiled to native RISC-V code on the device itself.

Try it now at lightplayer.app — the Studio runs entirely in your browser, and the built-in simulator means you don't need any hardware to start playing.

Screenshots are CI-maintained UI captures from the story test suite — they update automatically as the app changes.

What makes it different:

• GLSL, compiled on the device. A full compiler stack (GLSL → LPIR → native RV32) runs on the microcontroller, executing shaders in Q16.16 fixed point — no floating-point unit required.
• Studio in your browser. Live previews, node-based project editing, and AI-assisted shader authoring (bring your own API key). The built-in simulator runs the real firmware as a WASM worker — no hardware needed to try everything.
• Plug it in. USB-first: connect a device and go. No WiFi provisioning dance.
• Self-contained, open projects. A project is a folder of JSON and GLSL files. Open format, AGPL-licensed platform.

Status: alpha

LightPlayer is in alpha. A determined tester can get real value today: author GLSL effects in the browser studio, run them in the simulator without hardware, and drive WS2812-class strips from an ESP32-C6 over USB. Expect rough edges and breaking changes — there are no project-format or protocol compatibility promises yet. The Studio requires a Chromium-based browser (it uses WebSerial and OPFS). Issue reports are welcome.

Quick Start

The fastest path is the hosted Studio at lightplayer.app (deployed from main; no install, no hardware — open it in a Chromium-based browser).

To run everything from source:

# Clone the repo
git clone https://github.com/light-player/lightplayer.git
cd lightplayer

# Initialize your development environment
scripts/dev-init.sh

# Run the browser Studio (with built-in simulator — no hardware needed)
just studio-dev

Then open the Studio in a Chromium-based browser, open an example project, and connect it to the browser simulator.

For a headless engine demo without the Studio:

just demo
just demo -- <example-name>   # run other examples

Run on hardware (ESP32-C6)

To flash firmware, push the examples/basic project over USB serial, and run it on real hardware:

just demo-esp32c6-host

You need an ESP32-C6 board connected by USB, the RISC-V target installed (the recipe runs install-rv32-target), and espflash on your PATH for flashing.

Wiring (GPIO is hardcoded today): connect a WS2812-class addressable strip (or other device driven the same way) to GPIO 18 as the data line—not the pin field in examples/basic/src/strip.output/node.json, which the firmware does not use yet. The firmware initializes a buffer for 256 LEDs; the basic demo mapping uses 241 pixels, which fits in that limit.

For an empty flash and firmware only (no project push), use just demo-esp32c6-standalone.

Development

1. Initialize the development environment:

   scripts/dev-init.sh

   This will:

   • Check for required tools (Rust, Cargo, rustup, just, oxipng)
   • Verify Rust version meets minimum requirements (1.90.0+)
   • Install the RISC-V target (riscv32imac-unknown-none-elf) if needed
   • Set up git hooks (pre-commit hook runs just check)

2. Required tools:

   • Rust toolchain (1.90.0 or later) - Install Rust
   • just - Task runner: cargo install just or via package manager
   • oxipng - Lossless PNG optimizer for Studio story image baselines: cargo install oxipng or brew install oxipng

3. Common development commands:

   • just fci - Fix, check, build, and test the whole project. Do this before you submit a PR.
   • just fci-app - Fix, check, build, and test the application.
   • just fci-glsl - Fix, check, build, and test the GLSL compiler.

See just --list for all available commands, and docs/development.md for deeper workflows: hardware manifests, schema generation, GPIO calibration, and on-hardware firmware tests.

Repository Structure

• lp-app/ Browser Studio (Dioxus + WASM): studio UI, server/client, device link, OPFS filesystem, browser firmware host
• lp-core/ Platform core (lpc-* crates): rendering engine, data model, wire protocol, registry, hardware manifests
• lp-shader/ GLSL compiler: frontend (via naga), LightPlayer IR, backends (native RV32 JIT, Cranelift, WASM), Q16.16 fixed-point math, and the filetest suite — see lp-shader/README.md
• lp-fw/ Firmware: ESP32-C6 (fw-esp32c6), emulator firmware (fw-emu), browser worker (fw-browser), integration tests (fw-tests)
• lp-gfx/ GPU rendering layer (wgpu) used for Studio previews
• lp-emu/ Architecture-neutral emulator substrate (lp-emu-core) and host↔guest ABI (lp-emu-abi) shared by the architecture emulators
• lp-riscv/ RISC-V 32-bit emulator, instruction encoding/decoding, and ELF tooling
• lp-cli/ Developer CLI (projects, dev server, hardware manifests, GPIO calibration); runs from a source checkout
• lp-base/ Foundation crates: collections, filesystem, performance, recovery
• examples/ Example LightPlayer projects
• schemas/ Generated JSON Schemas for project/node/hardware files
• docs/ Documentation, ADRs, and design notes
• scripts/ Build scripts and development utilities
• third_party/ Vendored forks (naga, and friends)

Acknowledgments

LightPlayer follows in the footsteps of the LED-art projects that shaped this space:

• Pixelblaze by Ben Hencke — the pioneer of live-coded LED shaders on a microcontroller, and proof that pattern authoring could be joyful. Ben has also been generous with ideas in conversation, including embedded trig techniques that found their way into LightPlayer. If you want polished ready-to-go hardware with a brilliant integrated editor, buy a Pixelblaze.
• WLED — the project that brought addressable LEDs to everyone; its community and effect vocabulary informed many of LightPlayer's goals.

LightPlayer would not be possible without the amazing work of these projects:

• Cranelift - Fast, secure compiler backend (forked to support 32-bit RISC-V and no_std)
• Naga - Shader IR and glsl-in GLSL frontend (used by lps-frontend)
• pp-rs - GLSL preprocessor fork, patched in [patch.crates-io] in the workspace Cargo.toml so naga glsl-in works on no_std targets
• glsl-parser - GLSL parser ( forked for spans)
• Lygia - Shader library (source for lpfn built-in functions)
• DirectXShaderCompiler - HLSL compiler ( compiler architecture inspiration)
• esp-hal - Pure Rust ESP32 bare metal HAL (used for ESP32 firmware)
• GLSL Specification - GLSL language reference
• RISC-V Instruction Set Manual - RISC-V architecture documentation
• RISC-V ELF psABI Specification - RISC-V ABI documentation

... and many more not listed. Thank you to everyone in the open source community for your work.

Special thanks to @SeanConnell for his support and guidance throughout the development of the project.

License

LightPlayer-owned code is licensed under the GNU Affero General Public License version 3 or later (AGPL-3.0-or-later). See LICENSE for the full license text.

Third-party code, vendored forks, and dependencies remain under their own licenses.

Contributions are accepted under the terms in CONTRIBUTING.md.