Stream Deck Plus Controller

A custom, lightweight Python daemon for the Elgato Stream Deck Plus (Stream Deck +) running on Linux (optimized for Arch Linux + Niri Wayland).

This daemon uses the open-source python-elgato-streamdeck library to drive the device inputs and displays. It renders a real-time system performance monitor on the touchscreen, maps physical dials to hardware controls, and binds LCD keys to desktop commands and toggle-based Nushell layout scripts.

---

🚀 Features

• Catppuccin Mocha Theme: Drawn using Pillow and styled matching the rest of your system dotfiles.
• 800×100 Touchscreen Dashboard:
  • Segment 0 (Volume): Real-time volume level indicator, mute status, and progress bar.
  • Segment 1 (CPU): Current CPU utilization percentage and progress bar.
  • Segment 2 (RAM): Memory usage tracker (Used GB / Total GB) and progress bar.
  • Segment 3 (GPU): Light-weight discrete AMD GPU utilization and temperature statistics polled directly from sysfs (RX 7900 XTX) with a fallback to NVIDIA GPU nvidia-smi queries.
• Dynamic Keys:
  • Mic Mute (Key 3): Toggles microphone state via wpctl. Dynamically changes the key icon (active vs. slash-muted) and colors (green for active, red for muted) based on hardware feedback.
  • OBS Rec (Key 5): Connects to OBS Studio via OBS WebSocket v5 to toggle recording. Automatically parses your local OBS configuration files at startup to load the WebSocket port and authentication password dynamically.
  • Normal / Vertical Recording Toggles (Keys 0 & 1): Execute toggle scripts in your dotfiles helper folder. Launches Niri terminal layouts and OBS profiles on first press, and closes them all cleanly on second press.
• Hardware Dial Mapping:
  • Dial 0: Rotate to adjust master volume / Push to toggle mute (wpctl).
  • Dial 1: Rotate to adjust screen backlight brightness (brightnessctl).
  • Dial 2: Rotate to adjust mic volume / Push to toggle mic mute (wpctl).
• Aesthetic Icon Alignment: Supports custom pixel shifts (icon_offset_x) in the key mapping config to manually center monospaced Nerd Font icons (like the Terminal icon) perfectly on the LCD keys.

---

🛠️ Prerequisites & Installation

1. System Dependencies

Ensure you have the required USB/HID libraries installed. On Arch Linux:

sudo pacman -S libusb systemd

2. Configure USB Permissions (Udev Rules)

By default, standard user accounts do not have write access to raw USB HID devices. To run the daemon without using sudo, you must install udev rules:

1. Create a rules file at /etc/udev/rules.d/99-streamdeck.rules:

   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0063", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0090", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="008f", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0080", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0084", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0086", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="009a", TAG+="uaccess"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="00a5", TAG+="uaccess"
   

   (Note: The udev.rules file in this repository contains the same rules ready to copy.)

2. Reload and trigger the udev daemon to apply:

   sudo udevadm control --reload-rules && sudo udevadm trigger
   

3. Unplug and replug your Stream Deck Plus to apply the new permissions.

---

🏃 Running the Daemon

Initial Sync (Using uv)

Ensure uv is installed, then run the entrypoint. It will automatically initialize a virtual environment and load dependencies:

uv run main.py

Autostart via Systemd (Recommended)

A user-level systemd service is tracked in your dotfiles repository. To sync and control it:

1. Run dotfiles sync script (Nushell) to symlink the service file:

   use ~/dev/dotfiles/nushell/modules/system.nu dotfiles
   dotfiles
   

2. Reload and enable the service to start automatically with your graphical session:

   systemctl --user daemon-reload
   systemctl --user enable --now streamdeck-daemon.service
   

3. To view logs or check status:

   systemctl --user status streamdeck-daemon.service
   journalctl --user -u streamdeck-daemon.service -n 50 -f
   

---

⚙️ Configuration

You can customize theme colors, font choices, script paths, and OBS settings in config.py:

• Colors: Modify the RGB color tuples in COLORS to change the layout design.
• Intervals: Modify POLLING_INTERVAL to speed up or slow down telemetry collection.
• Key Actions: Map commands, actions, custom labels, and offsets in actions.py.