# alexledevdu22/ambilight architecture

> Architecture diagram of the GitHub repository alexledevdu22/ambilight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexledevdu22/ambilight
- Repository: https://github.com/alexledevdu22/ambilight

## Overview

This is a desktop Ambilight system with a Python controller and Arduino LED firmware. The main workflow is user configuration in the Tkinter UI, followed by screen capture and edge-color mapping or audio analysis and color generation; the controller smooths colors and sends them over serial to the LED strip. The firmware also accepts infrared remote controls for standalone effects. The tree documents additional mouse-responsive and Spotify features, but their detailed wiring is not shown in the sampled source, so those links are kept limited.

Main entry points: [`client/main.py`](https://github.com/alexledevdu22/ambilight/blob/main/client/main.py) (Controller loop), [`arduino-ambilight/src/main.cpp`](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/main.cpp) (Firmware loop), [`client/ui.py`](https://github.com/alexledevdu22/ambilight/blob/main/client/ui.py) (Settings UI), [`client/sound_ambient.py`](https://github.com/alexledevdu22/ambilight/blob/main/client/sound_ambient.py) (Sound effects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop controller"]
  node_ui["Settings UI<br/>[ui.py]"]
  node_app["Controller loop<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_serial["Serial LED sender<br/>[led_strip.py]"]
end

subgraph group_inputs["Capture and effects"]
  node_capture["Screen capture<br/>[screen_capture.py]"]
  node_mapper["Edge mapper<br/>[led_mapper.py]"]
  node_audio_sources["Audio sources<br/>[audio_sources.py]"]
  node_sound["Sound effects<br/>[sound_ambient.py]"]
  node_mouse["Mouse ambient<br/>[mouse.py]"]
end

subgraph group_firmware["Arduino firmware"]
  node_firmware_main["Firmware loop<br/>[main.cpp]"]
  node_buffer["Serial frame parser<br/>[buffer.cpp]"]
  node_remote["IR decoder<br/>[remote.cpp]"]
  node_modes["LED modes<br/>[modes.cpp]"]
  node_leds["LED driver<br/>[leds.cpp]"]
end

subgraph group_integrations["External integrations"]
  node_display(("Screen"))
  node_audio_device(("Audio device"))
  node_spotify(("Spotify"))
  node_ir_remote(("IR remote"))
  node_led_strip(("LED strip"))
end

node_user(("User"))

node_user -->|"sets options"| node_ui
node_ui -->|"start or stop"| node_app
node_ui -->|"saves settings"| node_config
node_app -->|"loads settings"| node_config
node_app -->|"captures frames"| node_capture
node_display -->|"provides image"| node_capture
node_app -->|"maps frame"| node_mapper
node_app -.->|"updates frame"| node_mouse
node_app -->|"gets colors"| node_sound
node_sound -->|"reads samples"| node_audio_sources
node_audio_device -->|"provides audio"| node_audio_sources
node_spotify -.->|"track metadata"| node_sound
node_app -->|"sends colors"| node_serial
node_serial -->|"serial data"| node_firmware_main
node_firmware_main -->|"checks frames"| node_buffer
node_buffer -->|"writes RGB"| node_leds
node_ir_remote -->|"sends commands"| node_remote
node_firmware_main -->|"reads codes"| node_remote
node_firmware_main -->|"dispatches controls"| node_modes
node_modes -->|"renders effects"| node_leds
node_leds -->|"drives LEDs"| node_led_strip

click node_ui "https://github.com/alexledevdu22/ambilight/blob/main/client/ui.py"
click node_app "https://github.com/alexledevdu22/ambilight/blob/main/client/main.py"
click node_config "https://github.com/alexledevdu22/ambilight/blob/main/client/config.py"
click node_capture "https://github.com/alexledevdu22/ambilight/blob/main/client/screen_capture.py"
click node_mapper "https://github.com/alexledevdu22/ambilight/blob/main/client/led_mapper.py"
click node_audio_sources "https://github.com/alexledevdu22/ambilight/blob/main/client/audio_sources.py"
click node_sound "https://github.com/alexledevdu22/ambilight/blob/main/client/sound_ambient.py"
click node_mouse "https://github.com/alexledevdu22/ambilight/blob/main/client/mouse.py"
click node_serial "https://github.com/alexledevdu22/ambilight/blob/main/client/led_strip.py"
click node_firmware_main "https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/main.cpp"
click node_buffer "https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/buffer.cpp"
click node_remote "https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/remote.cpp"
click node_modes "https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/modes.cpp"
click node_leds "https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/leds.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_app,node_config,node_serial,node_user toneBlue
class node_capture,node_mapper,node_audio_sources,node_sound,node_mouse toneAmber
class node_firmware_main,node_buffer,node_remote,node_modes,node_leds toneMint
class node_display,node_audio_device,node_spotify,node_ir_remote,node_led_strip toneRose
```

## Components

### Desktop controller

- [Settings UI](https://github.com/alexledevdu22/ambilight/blob/main/client/ui.py): `client/ui.py`
- [Controller loop](https://github.com/alexledevdu22/ambilight/blob/main/client/main.py): `client/main.py`
- [Configuration](https://github.com/alexledevdu22/ambilight/blob/main/client/config.py): `client/config.py`
- [Serial LED sender](https://github.com/alexledevdu22/ambilight/blob/main/client/led_strip.py): `client/led_strip.py`

### Capture and effects

- [Screen capture](https://github.com/alexledevdu22/ambilight/blob/main/client/screen_capture.py): `client/screen_capture.py`
- [Edge mapper](https://github.com/alexledevdu22/ambilight/blob/main/client/led_mapper.py): `client/led_mapper.py`
- [Audio sources](https://github.com/alexledevdu22/ambilight/blob/main/client/audio_sources.py): `client/audio_sources.py`
- [Sound effects](https://github.com/alexledevdu22/ambilight/blob/main/client/sound_ambient.py): `client/sound_ambient.py`
- [Mouse ambient](https://github.com/alexledevdu22/ambilight/blob/main/client/mouse.py): `client/mouse.py`

### Arduino firmware

- [Firmware loop](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/main.cpp): `arduino-ambilight/src/main.cpp`
- [Serial frame parser](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/buffer.cpp): `arduino-ambilight/src/buffer.cpp`
- [IR decoder](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/remote.cpp): `arduino-ambilight/src/remote.cpp`
- [LED modes](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/modes.cpp): `arduino-ambilight/src/modes.cpp`
- [LED driver](https://github.com/alexledevdu22/ambilight/blob/main/arduino-ambilight/src/leds.cpp): `arduino-ambilight/src/leds.cpp`

### External integrations

- **Screen**
- **Audio device**
- **Spotify**
- **IR remote**
- **LED strip**

### Other components

- **User**

## Connections

- User → Settings UI: sets options
- Settings UI → Controller loop: start or stop
- Settings UI → Configuration: saves settings
- Controller loop → Configuration: loads settings
- Controller loop → Screen capture: captures frames
- Screen → Screen capture: provides image
- Controller loop → Edge mapper: maps frame
- Controller loop → Mouse ambient: updates frame
- Controller loop → Sound effects: gets colors
- Sound effects → Audio sources: reads samples
- Audio device → Audio sources: provides audio
- Spotify → Sound effects: track metadata
- Controller loop → Serial LED sender: sends colors
- Serial LED sender → Firmware loop: serial data
- Firmware loop → Serial frame parser: checks frames
- Serial frame parser → LED driver: writes RGB
- IR remote → IR decoder: sends commands
- Firmware loop → IR decoder: reads codes
- Firmware loop → LED modes: dispatches controls
- LED modes → LED driver: renders effects
- LED driver → LED strip: drives LEDs