lava_lamp.py

Single-file async Python client for the lava lamp RGB API.

Use It

Copy lava_lamp.py into your project, then add its only runtime dependency:

uv add httpx

or

pip install httpx

For local development:

uv sync --dev
uv run pytest

One-Shot RGB

import asyncio

from lava_lamp import LavaLampClient


async def main() -> None:
    async with LavaLampClient() as client:
        rgb = await client.get_rgb()
        print(rgb)


asyncio.run(main())

Stream Updates

import asyncio

from lava_lamp import LavaLampClient


async def main() -> None:
    async with LavaLampClient("https://api.neurolavalamp.com") as client:
        async for state in client.stream_states():
            print(state.rgb_list, state.hex, state.live)


asyncio.run(main())

You can also pass a callback:

await client.watch(lambda state: print(state.rgb))

To emit streamed updates later while preserving the original color order and spacing, pass a decimal delay in seconds:

client = LavaLampClient(emit_delay_seconds=1.5)

API

LavaLampState exposes:

• rgb: (red, green, blue)
• rgb_list: [red, green, blue]
• hex: CSS-style hex color
• last_set_unix_ms: timestamp for last color update
• live: whether vedal is live/lamp is streaming

The default base URL is https://api.neurolavalamp.com, but pass another URL to LavaLampClient(...) if the server moves.