Guide for running HyperHDR in an Ubuntu Distrobox on Bazzite, including Pipewire screen capture dependencies and desktop menu integration.

HyperHDR-Ambilight-Distrobox-Setup.md

HyperHDR Setup: Ambilight in an Ubuntu Distrobox

This guide explains how to install HyperHDR within an Ubuntu Distrobox on Bazzite (or Fedora Atomic) to achieve Ambilight functionality using Pipewire screen capture.

1. Create the HyperHDR Distrobox

Create a dedicated Ubuntu container. We use Ubuntu because HyperHDR provides excellent .deb support and easy access to required libraries.

distrobox create --name hyperhdr-box --image ubuntu:24.04
distrobox enter hyperhdr-box

2. Install Dependencies & HyperHDR

Inside the container, update your sources and install the necessary Pipewire and Portal libraries required for screen capturing.

# Update system
sudo apt update && sudo apt upgrade -y
sudo apt install lsb-release software-properties-common -y
sudo add-apt-repository universe -y
sudo apt update

# Install Pipewire, Wireplumber and Portal dependencies
sudo apt install -y \
   pipewire \
   libpipewire-0.3-0t64 \
   pipewire-pulse \
   wireplumber \
   xdg-desktop-portal \
   xdg-desktop-portal-kde \
   qtwayland5

Install HyperHDR

Follow the official HyperHDR Installation Guide to download and install the latest .deb package. Generally, this involves:

1. Downloading the .deb from their GitHub Releases.
2. Running sudo apt install ./hyperhdr_xxxx.deb.

---

3. Configuration & Desktop Integration

To make HyperHDR feel like a native app on Bazzite, we will create a custom .desktop file and export it.

Create the Desktop Entry

Create a file (e.g., in ~/desktop-exports/hyperhdr.desktop) with the following content:

[Desktop Entry]
Name=HyperHDR
Comment=Ambient Lighting Software (GUI Mode)
Exec=hyperhdr
Icon=/home/tristan/desktop-exports/icons/hyperhdr.png
Terminal=false
Type=Application
Categories=Graphics;Settings;
StartupNotify=true

Export to Host

Run this command inside the distrobox to make the application visible in your Bazzite/KDE application menu:

distrobox-export --app hyperhdr --extra-flags "--user"

(Note: Using --app hyperhdr directly is usually sufficient if the binary is in /usr/bin/. Your manual .desktop file approach works well if you want a custom icon path.)

---

Important Note on Screen Capture

Since you are on Bazzite (Wayland), HyperHDR needs to communicate with the xdg-desktop-portal to capture the screen. When you start HyperHDR for the first time and enable "Pipewire" capture, your desktop will likely ask for permission to share the screen.

Hier ist der spezifische Abschnitt für deinen HyperHDR-Guide, der genau erklärt, wie man die Bildschirmfreigabe (Screen Capture) zurücksetzt:

---

Resetting Screen Capture Permissions

If the Screen Share pop-up no longer appears, you can reset the authorization in two ways:

1. Via KDE System Settings (Precise)

This is the best way to handle it without affecting other applications:

1. Open System Settings and go to Security & Privacy → Application Permissions.
2. Select Screen Capture from the left sidebar.
3. Look for the HyperHDR entry (it might also appear under the name of your Distrobox).
4. Change the status to "Always Ask" or click the Minus (-) button to delete the entry.
5. Restart HyperHDR; the permission dialog should now reappear.

2. Via Terminal (Manual Reset)

If the GUI entry is missing or not working, you can manually reset the portal service's memory:

• Targeted Reset (Recommended): Resets only the screen-sharing permissions for all portal-based apps:

flatpak permission-reset org.freedesktop.portal.Desktop

• Global Reset: If you want to clear all permission decisions for every app (the "nuclear" option):

flatpak permission-reset --all