{"id":27488354,"url":"https://github.com/sshcrack/led-matrix","last_synced_at":"2026-06-16T19:00:42.445Z","repository":{"id":219819043,"uuid":"749951819","full_name":"sshcrack/led-matrix","owner":"sshcrack","description":"A powerful led matrix software with a lots of plugins and visualizations","archived":false,"fork":false,"pushed_at":"2026-06-15T17:26:45.000Z","size":140565,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-15T19:24:38.331Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sshcrack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-01-29T17:58:17.000Z","updated_at":"2026-06-15T17:26:17.000Z","dependencies_parsed_at":"2024-03-30T19:34:30.371Z","dependency_job_id":"1cf22f30-3704-41ca-aea7-0bdea94e99b7","html_url":"https://github.com/sshcrack/led-matrix","commit_stats":null,"previous_names":["sshcrack/led-matrix"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/sshcrack/led-matrix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshcrack%2Fled-matrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshcrack%2Fled-matrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshcrack%2Fled-matrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshcrack%2Fled-matrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshcrack","download_url":"https://codeload.github.com/sshcrack/led-matrix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshcrack%2Fled-matrix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34419350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-16T19:56:45.196Z","updated_at":"2026-06-16T19:00:42.415Z","avatar_url":"https://github.com/sshcrack.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌈 LED Matrix Controller\n\n\u003e [!TIP]\n\u003e This project is still maintained, but I just don't have any ideas what to do right now, I'm open for suggestions!\n\n\u003cdiv align=\"center\"\u003e\n\nTransform your space with a **powerful C++ application** that turns RGB LED matrices into stunning digital canvases. Create mesmerizing visual effects, display real-time data, and control everything remotely with our comprehensive plugin ecosystem.\n\n**✨ Perfect for makers, developers, and digital artists ✨**\n\n\u003e **🎯 Recommended:** 128x128 matrix + Raspberry Pi 4 for optimal results!\n\n[![GitHub stars](https://img.shields.io/github/stars/sshcrack/led-matrix?style=for-the-badge)](https://github.com/sshcrack/led-matrix/stargazers)\n[![C++](https://img.shields.io/badge/C%2B%2B-23-blue?style=for-the-badge\u0026logo=cplusplus)](https://en.cppreference.com/w/cpp/23)\n[![Platform](https://img.shields.io/badge/Platform-Raspberry%20Pi-red?style=for-the-badge\u0026logo=raspberrypi)](https://www.raspberrypi.org/)\n[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers\u0026message=Open\u0026color=blue\u0026style=for-the-badge)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/sshcrack/led-matrix)\n\n\u003c/div\u003e\n\n## 📋 Table of Contents\n\n- [✨ Features](#-features)\n- [🔌 Components](#-components)\n- [🛠️ Hardware Support](#️-hardware-support)\n- [📋 Prerequisites](#-prerequisites)\n- [🚀 Quick Start Guide](#-quick-start-guide)\n- [🖥️ Desktop App](#️-desktop-app)\n- [🎯 Usage Guide](#-usage-guide)\n- [🌐 API Reference](#-api-reference)\n- [🔧 Troubleshooting](#-troubleshooting)\n- [🔌 Plugin Development](#-plugin-development)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n\n## 🎬 Demonstration\n\nBelow are some example scenes and effects from the included plugins:\n\n\u003cdiv align=\"center\"\u003e\n\n| AmbientScenes: Clock | AmbientScenes: Starfield | AudioVisualizer: Beat Spectrum | FractalScenes: Game of Life | FractalScenes: Julia Set |\n|:-------------------:|:-----------------------:|:----------------------------:|:--------------------------:|:------------------------:|\n| ![](plugins/AmbientScenes/img/clock.gif) | ![](plugins/AmbientScenes/img/starfield.gif) | ![](plugins/AudioVisualizer/img/beat_spectrum_normal.gif) | ![](plugins/FractalScenes/img/game_of_life.gif) | ![](plugins/FractalScenes/img/julia_set.gif) |\n\n| FractalScenes: Wave | GameScenes: Maze | GameScenes: Ping Pong | GameScenes: Snake | GameScenes: Tetris |\n|:------------------:|:---------------:|:---------------------:|:----------------:|:-----------------:|\n| ![](plugins/FractalScenes/img/wave.gif) | ![](plugins/GameScenes/img/maze.gif) | ![](plugins/GameScenes/img/ping_pong.gif) | ![](plugins/GameScenes/img/snake.gif) | ![](plugins/GameScenes/img/tetris.gif) |\n\n| GithubScenes: Watermelon Plasma | GithubScenes: Wave | RGBMatrixAnimations: Rain | RGBMatrixAnimations: Sparks | Shadertoy |\n|:------------------------------:|:------------------:|:------------------------:|:--------------------------:|:---------:|\n| ![](plugins/GithubScenes/img/watermelon_plasma.gif) | ![](plugins/GithubScenes/img/wave.gif) | ![](plugins/RGBMatrixAnimations/img/rain.gif) | ![](plugins/RGBMatrixAnimations/img/sparks.gif) | ![](plugins/Shadertoy/img/shadertoy.gif) |\n\n| SpotifyScenes: Cover Only | WeatherOverview: Night Clear |\n|:------------------------:|:---------------------------:|\n| ![](plugins/SpotifyScenes/img/cover_only.gif) | ![](plugins/WeatherOverview/img/night-clear.gif) |\n\n\n\u003c/div\u003e\n\n---\n## ✨ Features\n\n### 🎮 **Comprehensive Control System**\n- **REST API server** for seamless remote control\n- **PWA** and **a website** for on-the-go management\n- **11+ specialized plugins** for unlimited visual variety\n- **Preset management** for quick scene switching\n- **Advanced scheduling** - Automatically switch presets based on time and day\n- **Automatic updates** - Keep your system up-to-date with the latest features and security fixes\n- **Real-time configuration** without restarts\n![Website Showcase](./docs/web-showcase.gif)\n\n### 🎨 **Rich Plugin Ecosystem**\nOur modular plugin architecture delivers an incredible variety of visual experiences across 11+ specialized plugins:\n\n#### 🌟 **AmbientScenes Plugin**\nCreate mesmerizing atmospheric effects:\n- **Starfield** - Simulates twinkling stars\n- **Metablob** - Organic fluid animations with flowing, morphing colors\n- **Clock** - Elegant digital timepieces with customizable styles\n\n#### 🎵 **SpotifyScenes Plugin**\nMusic comes alive on your matrix:\n- **Album Art Display** - Show current track artwork with smooth transitions\n- **Beat-synchronized Effects** - Visual rhythms that pulse with your music\n- **Now Playing Info** - Track, artist, and playback status visualization\n- **OAuth Integration** - Seamless Spotify account connection\n_[Setup required](./plugins/SpotifyScenes/README.md)_\n\n#### 🎮 **GameScenes Plugin**\nInteractive entertainment with AI-powered gameplay:\n- **Tetris** - Neural network AI plays automatically, optimizing piece placement\n- **Ping Pong** - Classic Pong with intelligent AI opponents\n- **Maze Generator** - Hunt-and-Kill algorithm creates mazes, A* pathfinding solves them\n\n#### 🧮 **FractalScenes Plugin**\nMathematical beauty in motion:\n- **Julia Set** - Animated fractal visualizations with evolving parameters\n- **Conways Game of Life**\n\n#### 🌦️ **WeatherOverview Plugin**\nReal-world data with style:\n- **Live Weather Display** - Current conditions with animated effects\n- **Weather Animations** - Visual rain, snow, sunshine effects\n\n#### 💻 **GithubScenes Plugin**\nThese include scenes, I've found on github:\nWatermelonplasma and Wave effects by [Knifa](https://github.com/Knifa/matryx-gl)\n\n#### 🎭 **Shadertoy Plugin**\nGPU-powered visual effects:\n- **Shader-based Animations** - Renders random (or selected) shaders from shadertoy\n- **Real-time Rendering** - Smooth, performance-optimized effects\n\n#### 🎨 **PixelJoint Plugin**\nScrapes the PixelJoint website and displays pixel art\n\n#### 🎆 **RGBMatrixAnimations Plugin**\nPhysics-based particle systems:\n- **Rain Effects** - Realistic precipitation with gravity\n- **Spark Systems** - Dynamic particle explosions and trails\n- **Gravity Simulations** - Physics-accurate particle behavior\n\n#### 🎵 **AudioVisualizer Plugin**\n[Real-time audio analysis](https://github.com/sshcrack/led-matrix/tree/master/plugins/AudioVisualizer):\n- **Frequency Spectrum** - Live audio visualization (setup required)\n- **Beat Detection** - Intelligent rhythm detection with visual effects\n- **Post-Processing Effects** - Flash and rotate effects triggered by beats\n- **REST API Control** - Manual effect triggering and configuration\n- **Multi-source Audio** - Various input methods supported\n\n#### 🛠️ **ExampleScenes Plugin**\nDevelopment foundation:\n- **Template Scenes** - Starting point for custom plugin development\n- **Reference Implementation** - Best practices demonstration\n\n#### 🌐 **Image \u0026 Media**\n- **Remote Image Loading** - Display images from URLs with artistic processing\n- **Multiple Format Support** - Handle various image types and sizes\n- **Dynamic Content** - Real-time image updates and transformations\n_(contained within the PixelJoint Scene)_\n\n### 🔧 **Advanced Features**\n- **Hardware abstraction** supporting various matrix configurations\n- **Cross-compilation support** for efficient Raspberry Pi deployment\n- **Emulator support** with SDL2 for development\n- **Configurable logging** with spdlog integration\n- **Persistent configuration** with JSON-based settings\n\n### ⏰ **Smart Scheduling System**\nTake automation to the next level with intelligent preset scheduling:\n- **Time-based switching** - Automatically change presets based on time of day\n- **Day-of-week scheduling** - Different configurations for weekdays vs weekends\n- **Multiple schedules** - Create unlimited schedules for different scenarios\n- **Cross-midnight support** - Schedules that span midnight work seamlessly\n- **Mobile management** - Create and edit schedules from your phone\n- **Real-time activation** - Schedule changes take effect immediately\n\n**Example Use Cases:**\n- **Office hours**: Bright, professional displays during work hours (9 AM - 5 PM, weekdays)\n- **Evening ambiance**: Warm, relaxing scenes after sunset (6 PM - 11 PM, daily)\n- **Weekend fun**: Colorful, dynamic animations on Saturday and Sunday\n- **Night mode**: Dim clock display during sleeping hours (11 PM - 7 AM)\n\n## 🔌 Components\n\n### 🖥️ **C++ Backend**\nThe heart of the system - a high-performance application that orchestrates everything:\n- **Scene rendering engine** with smooth animations at 60+ FPS\n- **Plugin management** with many loadable plugins\n- **Hardware interface** supporting multiple matrix configurations\n- **RESTful API server** for external control and integration\n- **Configuration persistence** and real-time updates\n\n### 🌐 **React Web App**\nA sleek web companion for remote control, also installable as a PWA on mobile:\n- **Intuitive scene selection** with live previews\n- **Real-time matrix control** from anywhere on your network\n- **Preset management** for quick configuration switching\n- **Schedule management** - Create and manage time-based automation\n- **Image upload functionality** for custom displays\n- Works on any device with a modern browser\n\nLocated in the `react-web/` directory with Vite, React, TypeScript and Tailwind CSS.\n\n## 🛠️ **Hardware Support**\n\n\u003e **⚠️ Important:** This project builds upon the excellent [rpi-rgb-led-matrix](https://github.com/hzeller/rpi-rgb-led-matrix) library. For detailed hardware setup, wiring diagrams, troubleshooting, and matrix-specific configuration, please refer to the [comprehensive documentation](https://github.com/hzeller/rpi-rgb-led-matrix) in that repository.\n\n### 🎯 **Recommended Hardware**\n\n\u003e **🌟 Recommended Setup:** For the best experience, we recommend a **128x128 LED matrix** (four 64x64 panels arranged in a 2x2 configuration) paired with a **Raspberry Pi 4**. This setup provides excellent resolution and performance for all visual effects!\n\n- **Raspberry Pi 4** (3B+ minimum) for optimal performance\n- **RGB LED matrix panels** with HUB75 interface:\n  - **Ideal**: Four 64x64 panels for 128x128 total resolution (multiple 32x32 should also work)\n- **Quality power supply** (5V with sufficient amperage - matrices are power-hungry!)\n- **[Active-3 Adapter from Electrodragon](https://www.electrodragon.com/product/rgb-matrix-panel-drive-board-raspberry-pi/)**, for alternatives [see here](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/adapter/README.md). \n\nConfigure your setup using command-line flags or the configuration file - the system adapts automatically!\n\n## 📋 **Prerequisites**\n\n## 🚀 **Quick Start Guide**\n\n### 🚀 **Automatic Installation (Recommended)**\n\nThe easiest way to install and configure the LED Matrix Controller is with the provided install script. This script will:\n- Download the latest release for your platform\n- Guide you through hardware configuration (matrix size, chain, parallel, etc.)\n- Optionally set up Spotify integration\n- Install the binary to `/opt/led-matrix`\n- Set up a systemd service for automatic startup\n\n**To get started, simply run:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/sshcrack/led-matrix/master/scripts/install_led_matrix.sh | bash\n```\n\nOr, if you have already cloned the repository:\n\n```bash\ncd scripts\nchmod +x install_led_matrix.sh\n./install_led_matrix.sh\n```\n\nThe script will ask you for your matrix configuration and any optional features. After installation, the service will start automatically.\nYou can now access the LED Matrix control at http://\u003cled_matrix_ip\u003e:8080/\n\n---\n\n## 🖥️ **Desktop App**\nThe Desktop App is used for compute intensive applications, like the AudioVisualizer or the Shadertoy.\n\n### 📥 **Installation**\n\n#### **Windows**\n1. Go to the [Releases page](https://github.com/sshcrack/led-matrix/releases)\n2. Download the latest `led-matrix-desktop-*-win64.exe` file\n3. Run the installer and follow the setup wizard\n\n#### **Linux**\n1. Go to the [Releases page](https://github.com/sshcrack/led-matrix/releases)\n2. Download the latest `led-matrix-desktop-*-Linux.tar.gz` file\n3. Extract and run:\n   ```bash\n   tar -xzf led-matrix-desktop-*-Linux.tar.gz\n   cd led-matrix-desktop-*\n   ./bin/led-matrix-desktop\n   ```\n\n### 🔧 **Usage**\nStart the Desktop App, enter your LED Matrix IP address, click \"Connect\" and you are ready to go!\n\n\n### 🖥️ **Manual Build \u0026 Development**\n\nIf you want to build from source or develop locally, follow these steps:\n\n\u003e **💡 Pro Tip:** You can also use our [devcontainer](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/sshcrack/led-matrix) which has all dependencies installed already!\n\n\n#### 🔧 **System Requirements**\n- **CMake 3.5+** for build system management\n- **C++23 compatible compiler** (GCC 12+ or Clang 15+)\n- **vcpkg package manager** for dependency management\n- **Python 3** with `jinja2` package (`apt install python3-jinja2 -y`)\n- **GraphicsMagick** and development headers (`apt install libgraphicsmagick1-dev`)\n\n#### 📱 **For Web Development**\n- **Node.js 20+** and pnpm\n\n#### **Building with CMake Presets (Recommended)**\n\nThis project uses CMake presets for easy configuration. Available presets:\n\n- **`cross-compile`** - Build for Raspberry Pi (ARM64)\n- **`emulator`** - Build with SDL2 emulator for development\n- **`desktop-linux`** - Build desktop app for Linux\n- **`desktop-windows`** - Build desktop app for Windows\n\n**For Raspberry Pi:**\n```bash\n# Configure and build for Raspberry Pi\ncmake --preset cross-compile\ncmake --build build --target install\n```\n\n**For Development/Emulator:**\n```bash\n# Configure and build emulator version\ncmake --preset emulator\ncmake --build --preset emulator\n```\n\n**For Desktop App:**\n```bash\n# Linux desktop app\ncmake --preset desktop-linux\ncmake --build --preset desktop-linux\n\n# Windows desktop app (on Windows)\ncmake --preset=desktop-windows\ncmake --build --preset desktop-windows\n```\n#### **Running the Emulator**\n\nTest your scenes without physical hardware using our SDL2-based emulator:\n\n```bash\n# Run with emulation (after building with emulator preset)\n./scripts/run_emulator.sh\n```\n\nPerfect for development, testing, and demonstrations!\n\n#### **Scene Preview GIFs**\n\nThe web interface shows animated GIF previews for each scene in the gallery. Previews are **committed to git** in the `scene_previews/` directory and deployed with the application.\n\n**Generate all scene previews:**\n```bash\n# Build the emulator first\ncmake --preset emulator\ncmake --build --preset emulator --target install\n\n# Generate previews (outputs to scene_previews/)\n./scripts/generate_scene_previews.sh --all\n```\n\n**Generate specific scenes:**\n```bash\n./scripts/generate_scene_previews.sh --scenes \"WaveScene,ColorPulseScene,FractalScene\"\n```\n\n**Generate from a list file:**\n```bash\n# Create a file with scene names (one per line, # for comments)\ncat \u003e my_scenes.txt \u003c\u003c EOF\nWaveScene\nColorPulseScene\n# FractalScene  (commented out)\nEOF\n\n./scripts/generate_scene_previews.sh --list my_scenes.txt\n```\n\n**Customize preview parameters:**\n```bash\n./scripts/generate_scene_previews.sh --all \\\n  --fps 20 \\\n  --frames 120 \\\n  --width 128 \\\n  --height 128\n```\n\n**Commit previews to git:**\n```bash\ngit add scene_previews/\ngit commit -m \"Update scene previews\"\n```\n\n**Desktop-dependent scenes** (VideoScene, AudioSpectrumScene, ShadertoyScene, etc.) cannot be generated headlessly and must be captured manually:\n```bash\n# 1. Start the emulator (non-headless) and the desktop app\n./scripts/run_emulator.sh \u0026\n./desktop_build/bin/led-matrix-desktop \u0026\n\n# 2. Capture desktop-dependent scene previews\n./scripts/capture_desktop_preview.sh --api-url http://localhost:8080\n\n# Options:\n#   --scenes AudioSpectrumScene,ShadertoyScene   # specific scenes only\n#   --duration 8                                 # capture 8 seconds per scene\n#   --output ./scene_previews                    # output directory\n```\n\n**Full deploy workflow:**\n```bash\n# 1. Generate/update previews (outputs to scene_previews/)\n./scripts/generate_scene_previews.sh --all\n\n# 2. Commit previews to git\ngit add scene_previews/\ngit commit -m \"Update scene previews\"\n\n# 3. Cross-compile and deploy\ncmake --preset cross-compile\ncmake --build \u003cbuild_dir\u003e\ncmake --build \u003cbuild_dir\u003e --target install\n\n# Or use the build_upload.sh helper script\n./scripts/build_upload.sh\n```\n\n### 🌐 **Web App Development**\n\nRun the development server in minutes:\n\n1. **Navigate to the app directory:**\n   ```bash\n   cd react-web\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   pnpm install\n   ```\n\n3. **Launch the dev server:**\n   ```bash\n   pnpm run dev\n   ```\n\n## 🎯 **Usage Guide**\n\n### 🐌 **Manual Installation**\n\nDownload the built binary from GitHub releases (`led-matrix-arm64.tar.gz` for RPI 3 64-bit) and extract it at `/opt/led-matrix`\n\n```bash\nsudo ./main [options]\n```\n\n\u003e **🔑 Note:** `sudo` is required for GPIO access on Raspberry Pi.\n\n### ⚙️ **Essential Configuration Options**\n\n```bash\n# Basic matrix setup\n--led-rows=32              # Rows per panel\n--led-cols=64              # Columns per panel\n--led-chain=2              # Number of chained panels\n--led-parallel=1           # Number of parallel chains\n\n# Visual settings\n--led-brightness=80        # Brightness (0-100)\n--led-pwm-bits=11         # Color depth (1-11)\n--led-limit-refresh=120   # Refresh rate limit\n\n# Hardware-specific\n--led-gpio-mapping=adafruit-hat    # For Adafruit HAT/Bonnet\n--led-slowdown-gpio=1             # Timing adjustment for Pi models\n```\n\n\u003e **📖 For comprehensive configuration options**, including troubleshooting flickering displays, timing adjustments, and advanced setups, see the [rpi-rgb-led-matrix documentation](https://github.com/hzeller/rpi-rgb-led-matrix?tab=readme-ov-file#types-of-displays).\n\n### 🗂️ **Configuration Management**\n\nThe application uses a smart configuration system:\n\n- **`config.json`** - Automatically created in the application directory\n- **Persistent settings** - Scene presets, API configurations, plugin settings\n- **Hot-reload support** - Many settings update without restart\n- **Backup-friendly** - JSON format for easy version control\n\n### 📊 **Logging System**\n\nFine-tune logging for development and debugging:\n\n```bash\n# Set log level via environment variable\nSPDLOG_LEVEL=debug ./main\n\n# Available levels: trace, debug, info, warn, error, critical, off\n```\n\nAll logs output to console with timestamps and color coding for easy reading.\n\n## 🌐 **API Reference**\n_May be out of date_\n\nThe REST API provides powerful remote control capabilities at `http://\u003cdevice-ip\u003e:8080/`.\nBy default, the main index page will redirect you to the web controller (located at `/web`)\n\n### 📊 **Core Endpoints**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/status` | System status and current state |\n| `GET` | `/get_curr` | Current scene information |\n| `GET` | `/list_scenes` | Available scenes and plugins (includes `has_preview` and `needs_desktop` per scene) |\n| `GET` | `/toggle` | Toggle display on/off |\n| `GET` | `/skip` | Skip to next scene |\n\n### 🎛️ **Scene Management**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/set_preset?id=\u003cpreset_id\u003e` | Switch to specific preset |\n| `GET` | `/presets` | List all saved presets |\n| `POST` | `/preset?id=\u003cpreset_id\u003e` | Create/update preset |\n| `DELETE` | `/preset?id=\u003cpreset_id\u003e` | Delete preset |\n\n### 🖼️ **Media Control**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/list` | Available local images |\n| `GET` | `/image?url=\u003curl\u003e` | Fetch and display remote image |\n| `GET` | `/list_providers` | Available image providers |\n| `GET` | `/scene_preview?name=\u003cscene_name\u003e` | Preview GIF for a scene (if available) |\n\n\u003e **Scene Previews:** GIF files are pre-generated and committed to git in the `scene_previews/` directory. They are deployed to `\u003cinstall_dir\u003e/scene_previews/` and accessible via the `/scene_preview?name=\u003cscene_name\u003e` endpoint. To generate or update previews, use the `./scripts/generate_scene_previews.sh` script. After generating, commit the GIFs to git before deploying. The `/list_scenes` endpoint includes `has_preview` (bool) and `needs_desktop` (bool) fields per scene.\n\n### ⚙️ **System Control**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/set_enabled?enabled=\u003ctrue\\|false\u003e` | Enable/disable display |\n| `GET` | `/list_presets` | Detailed preset information |\n\n### ⏰ **Schedule Management**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/schedules` | List all schedules |\n| `GET` | `/schedule?id=\u003cschedule_id\u003e` | Get specific schedule details |\n| `POST` | `/schedule?id=\u003cschedule_id\u003e` | Create/update schedule |\n| `DELETE` | `/schedule?id=\u003cschedule_id\u003e` | Delete schedule |\n| `GET` | `/scheduling_status` | Get scheduling status and active preset |\n| `GET` | `/set_scheduling_enabled?enabled=\u003ctrue\\|false\u003e` | Enable/disable scheduling |\n\n### 🎨 **Post-Processing Effects**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/post_processing/flash?duration=\u003cseconds\u003e\u0026intensity=\u003c0-1\u003e` | Trigger flash effect |\n| `GET` | `/post_processing/rotate?duration=\u003cseconds\u003e\u0026intensity=\u003c0-2\u003e` | Trigger rotation effect |\n| `GET` | `/post_processing/clear` | Clear all active effects |\n| `GET` | `/post_processing/status` | Get post-processing system status |\n| `GET` | `/post_processing/config` | Get beat detection configuration |\n\n#### **Post-Processing Examples**\n```bash\n# Quick flash effect\ncurl \"http://matrix-ip:8080/post_processing/flash?duration=0.3\u0026intensity=1.0\"\n\n# Slow rotation (720 degrees over 3 seconds)\ncurl \"http://matrix-ip:8080/post_processing/rotate?duration=3.0\u0026intensity=2.0\"\n\n# Clear all effects\ncurl \"http://matrix-ip:8080/post_processing/clear\"\n```\n\n**Beat Detection**: When using the AudioVisualizer plugin, beats are automatically detected from audio input and trigger flash effects. WebSocket clients receive `beat_detected` messages in real-time.\n\n#### **Schedule JSON Format**\n```json\n{\n  \"id\": \"work-hours\",\n  \"name\": \"Work Hours Display\",\n  \"preset_id\": \"office-preset\",\n  \"start_hour\": 9,\n  \"start_minute\": 0,\n  \"end_hour\": 17,\n  \"end_minute\": 30,\n  \"days_of_week\": [1, 2, 3, 4, 5],\n  \"enabled\": true\n}\n```\n\n**Days of Week**: `0` = Sunday, `1` = Monday, ..., `6` = Saturday\n\n### 🔄 **Automatic Updates**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/update/status` | Get current update status and configuration |\n| `POST` | `/api/update/check` | Manually check for available updates |\n| `POST` | `/api/update/install` | Install available update (optional: `?version=\u003cversion\u003e`) |\n| `POST` | `/api/update/config` | Update auto-update configuration |\n| `GET` | `/api/update/releases?per_page=\u003ccount\u003e` | Get recent GitHub releases |\n\n#### **Update Status Response**\n```json\n{\n  \"auto_update_enabled\": true,\n  \"check_interval_hours\": 24,\n  \"current_version\": \"1.0.0\",\n  \"latest_version\": \"1.10.0\",\n  \"update_available\": true,\n  \"status\": 0,\n  \"error_message\": \"\"\n}\n```\n\n**Status Values**: `0`=Idle, `1`=Checking, `2`=Downloading, `3`=Installing, `4`=Error, `5`=Success\n\n#### **Update Configuration**\n```json\n{\n  \"auto_update_enabled\": true,\n  \"check_interval_hours\": 12\n}\n```\n\n#### **Update Examples**\n```bash\n# Check update status\ncurl \"http://matrix-ip:8080/api/update/status\"\n\n# Manually check for updates\ncurl -X POST \"http://matrix-ip:8080/api/update/check\"\n\n# Install latest update\ncurl -X POST \"http://matrix-ip:8080/api/update/install\"\n\n# Install specific version\ncurl -X POST \"http://matrix-ip:8080/api/update/install?version=1.10.0\"\n\n# Configure auto-updates\ncurl -X POST \"http://matrix-ip:8080/api/update/config\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"auto_update_enabled\": true, \"check_interval_hours\": 12}'\n\n# Get recent releases\ncurl \"http://matrix-ip:8080/api/update/releases?per_page=3\"\n```\n\n**Auto-Update**: When enabled, the system automatically checks for updates at the configured interval (default: 24 hours) and installs them if available. The service restarts automatically after installation. Updates can be managed via the web interface at `/updates`.\n\n## 🔧 **Troubleshooting**\n\n### 🚨 **Common Issues \u0026 Solutions**\n\n| Problem | Solution |\n|---------|----------|\n| **Matrix flickering** | Check power supply amperage - LEDs need significant current. Flickering can also be caused because the RPi has not enough performance |\n| **Permission errors** | Run with `sudo` for GPIO access |\n| **Slow performance** | Try upgrading your Pi to a newer model or reduce `--led-pwm-bits` |\n| **Can't connect to API** | Check firewall and ensure port 8080 is open |\n| **Panels not lighting up** | Verify `--led-panel-type` setting |\n| **Colors look wrong** | Adjust `--led-multiplexing` settings (try values 0-17) |\n\n\n\u003e **📚 For hardware-specific issues**, timing problems, or panel compatibility, consult the comprehensive [rpi-rgb-led-matrix troubleshooting guide](https://github.com/hzeller/rpi-rgb-led-matrix#troubleshooting).\n\n## 🔌 **Plugin Development**\n\nExtend the matrix with your own custom scenes and effects! Create powerful plugins that add new visual experiences, integrate external APIs, and provide custom functionality.\n\n### 📖 **Comprehensive Documentation**\n\nFor detailed plugin development, check out our **[Complete Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md)**!\n\nThis comprehensive guide covers:\n- 🏗️ **Plugin Architecture** - Understanding the modular system\n- 🚀 **Quick Start** - Get your first plugin running in minutes\n- 📚 **Core APIs** - Detailed documentation of shared libraries\n- 🎨 **Scene Development** - Create stunning visual effects\n- ⚙️ **Properties System** - Automatic serialization and validation\n- 🖼️ **Image Providers** - Custom image sources and processing\n- 🎭 **Post-Processing Effects** - Screen-wide effects and transformations\n- 🌐 **REST API Integration** - Custom endpoints and remote control\n- 💬 **Desktop Communication** - WebSocket messaging and data streaming\n- 🔧 **Advanced Features** - Resource loading, lifecycle hooks, and more\n- 📦 **Building and Testing** - CMake configuration and emulator testing\n- 🎯 **Best Practices** - Performance, error handling, and code organization\n\n### ⚙️ **Advanced Plugin Features**\n\n- **Property system** - Automatic API exposure and persistence with validation\n- **Image providers** - Custom image sources and processing\n- **Post-processing effects** - Screen-wide effects like flash and rotation\n- **REST API endpoints** - Extend the API with custom routes\n- **WebSocket communication** - Real-time messaging with desktop clients\n- **Resource loading** - Access plugin-specific assets and fonts\n- **Lifecycle hooks** - Initialize and cleanup resources properly\n\n### 📚 **Study These Plugin Examples**\n\n- **`ExampleScenes/`** - Simple starting template and basic patterns\n- **`AudioVisualizer/`** - Real-time audio analysis and visualization\n- **`WeatherOverview/`** - External API integration and animated displays\n- **`GameScenes/`** - Interactive content and game logic (Tetris, Pong, Maze)\n- **`FractalScenes/`** - Mathematical visualizations and complex algorithms\n- **`SpotifyScenes/`** - OAuth integration and music visualization\n- **`AmbientScenes/`** - Atmospheric effects and procedural generation\n\n### 🚀 **Get Started**\n\n\u003e [!NOTE]\n\u003e Linux-Specific: Make sure you have the necessary development packages installed:\n\u003e```bash\n\u003esudo apt install libasound2-dev python3-jinja2 pkg-config autoconf automake libtool python3 linux-libc-dev curl libltdl-dev libx11-dev libxft-dev libxext-dev libwayland-dev libxkbcommon-dev libegl1-mesa-dev libibus-1.0-dev mono-complete libxrandr-dev libxrandr2 wayland-protocols extra-cmake-modules xorg-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev libgtk-3-dev libayatana-appindicator3-dev\n\u003e```\n\n1. **Read the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md)**\n2. **Study existing plugins** for patterns and inspiration\n3. **Use the emulator** for development and testing\n4. **Share your creations** with the community!\n\n## 🤝 **Contributing**\n\nWe welcome contributions! Whether it's a bug fix, new feature, or awesome plugin - join our community.\n\n### 🚀 **Getting Started**\n\n1. **Fork the repository**\n2. **Create your feature branch:**\n   ```bash\n   git checkout -b feature/amazing-new-feature\n   ```\n3. **Make your changes** with clear, tested code\n4. **Commit with descriptive messages:**\n   ```bash\n   git commit -m 'Add some amazing new feature'\n   ```\n5. **Push to your branch:**\n   ```bash\n   git push origin feature/amazing-new-feature\n   ```\n6. **Open a Pull Request** with detailed description\n\n### 💡 **Contribution Ideas**\n\n- **New scene plugins** - Stocks, social media, ...\n- **Performance optimizations** - Faster rendering, lower memory usage\n- **Hardware support** - New matrix types, different GPIO mappings\n- **Mobile app features** - Better UI, offline mode, advanced controls\n- **Documentation** - Tutorials, examples, troubleshooting guides\n- **Assembly Guide** - 3D printable models, wiring\n\n### 📋 **Code Standards**\n\n- **C++23 features** encouraged where appropriate\n- **Clear variable names** and comprehensive comments\n- **Error handling** with `std::expected` where possible\n- **Thread safety** for multi-threaded operations\n\n## 📄 **License**\nSee the [LICENSE](LICENSE) file for details.\n\n### 🙏 **Acknowledgments**\n\n- **[rpi-rgb-led-matrix](https://github.com/hzeller/rpi-rgb-led-matrix)** by Henner Zeller - The foundation that makes this all possible\n- **[RGBMatrixAnimations](https://github.com/Footleg/RGBMatrixAnimations)** by Footleg - Particle system animations\n- **[Fluent Emoji by Microsoft](https://github.com/microsoft/fluentui-emoji)** - For the crystal ball emoji used as icon for the desktop app\n- **[matrix-gl](https://github.com/Knifa/matryx-gl)** and **[RGBMatrixAnimations](https://github.com/Footleg/RGBMatrixAnimations)** for awesome animations\n- **Open source community** - For the countless libraries and tools that power this project\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🌟 Star this repo if you found it helpful! 🌟**\n\nMade with ❤️ by sshcrack for the LED matrix community\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshcrack%2Fled-matrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshcrack%2Fled-matrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshcrack%2Fled-matrix/lists"}