$ show lunarring/lunar_tools
Lunar Tools is a Python library (v0.4) providing a modular toolkit for building interactive exhibitions. It bundles capabilities for audio recording/playback, speech-to-text and text-to-speech (OpenAI, ElevenLabs, Deepgram), real-time voice interaction via OpenAI Realtime API, webcam capture, MIDI controller input, multi-backend display rendering (OpenGL, OpenCV, Pygame, SDL/CUDA), and inter-process communication through OSC, ZMQ, and WebRTC (data channels and audio streaming). Additionally, it includes wrappers for image generation APIs (DALL-E 3, SDXL Turbo/Replicate, Flux on fal.ai) and LLM interfaces (OpenAI, Gemini, DeepSeek). The library is designed for quick prototyping of interactive installations, with example scripts in the `examples/` directory that demonstrate each module. The codebase is a collection of independent submodules rather than a monolith, each with its own set of dependencies. The most technically interesting parts are the WebRTC communication layer (`lunar_tools/comms/webrtc.py`), which handles SDP exchange via a local REST signaling server, supports automatic reconnection, and includes Opus codec tuning for high-quality audio. The custom codec (`lunar_tools/comms/webrtc_codec.py`) for encoding numpy arrays and messages into WebRTC data channels is a clean, reusable component. The ZMQ pair endpoint (`lunar_tools/comms/zmq.py`) offers a simple bidirectional JSON/image/audio channel. However, many modules suffer from inconsistent error handling, lack of type hints, and tight coupling to logging utilities. The overall architecture is pragmatic but not exemplary; it serves its purpose as a glue library for exhibition software. The repository includes a test suite (pytest) covering individual modules, CI/CD for PyPI publishing, and basic documentation in the README. Maintenance appears active (last commit within a month, though the date may be anomalous). It carries a BSD-3 license and has 296 GitHub stars, suggesting moderate community interest.
The LLM identified 3 files worth highlighting for reuse:
Implements a compact binary protocol for sending numpy arrays, JSON, and bytes over WebRTC data channels. Uses a header with a length prefix and custom struct format. The encode/decode functions are self-contained, handle type negotiation (dtype, shape), and can be extracted and reused in any WebRTC-based remote visualisation or data streaming project without modification.
Provides a ZMQ PAIR endpoint wrapper that handles JSON, JPEG-compressed images, and raw PCM audio in a unified interface. The class manages its own background polling thread, message queues, and configurable encoding quality. The pattern is generic and can be extracted to replace WebRTC with ZeroMQ in any peer-to-peer scenario that requires low-latency exchange of mixed data types.
Contains PyTorch-based image processing primitives: GaussianBlur, MedianBlur, FrequencyFilter (high/low-pass), and resize(). The FrequencyFilter class constructs a circular mask in frequency domain and applies it via FFT, which is non-trivial and correctly handles unshifted filters. These functions assume a specific tensor layout (BxCxHxW) and can be reused in any PyTorch image pipeline, though they lack batch support in the FrequencyFilter.