The HyperHDR project has excellent documentation on how to install and use it. For this guide, you'll install it on Raspberry Pi OS but you can reference the HyperHDR README for instructions on how to install it for Windows, LibreElec, Linux or macOS.
Prerequisite Pi Setup!
First, follow these instructions for setting up your Raspberry Pi. In a nutshell:
- Download Raspberry Pi imager
- Insert SD card in your computer
- Pick device (Pi 4 or Pi 5 are good choice)
- Raspberry Pi OS 64-Bit
- From Customizations General:
- WiFi credentials: enter your access point SSID and password
- Set locale settings for your time zone and keyboard layout
- From Customizations Services:
- Enable SSH with password authentication
- Chose your SD card from the storage options
- Write to the SD card
Installation
After setting up Raspberry Pi OS, open a terminal window and enter the following commands:
wget https://github.com/awawa-dev/HyperHDR/releases/download/v21.0.0.0/HyperHDR-21.0.0.0-Linux-aarch64.deb sudo apt install ./HyperHDR-21.0.0.0-Linux-aarch64.deb sudo systemctl enable [email protected]
This fetches the HyperHDR release, installs it and then enables the system service for it. By enabling the service, it will automatically run on boot.
Web GUI Access
The HyperHDR GUI is available on a port on your network after setup. You can access it directly on the Raspberry Pi or on another device on your network. If you're accessing it on the Pi, navigate to this address in the browser:
If you're accessing it on another device on your network, navigate to this address in your browser:
Update pi to your Raspberry Pi username.
After navigating to the GUI, you'll see the Overview page where you can see your system status at a glance along with the navigation menu on the left side of the screen.
Configuration
There are a lot of settings for HyperHDR and there is a detailed guide available in the repository as a reference. The steps below will get you up and running with the setup used in this guide.
First, navigate to the LED Hardware section. You'll select the settings for the Pixel Trinkey and your NeoPixels. On the LED Controller tab, select these settings:
- Controller type: adalight
- RGB byte order: RGB
- Output path: Auto
- Select "High speed serial AWA protocol"
- Baudrate: 2000000
If you're using RGBW NeoPixels, check off White channel calibration and enter 50% for White channel limit and update the red, green and blue values to dial in the colors. The values below were used with the RGBW NeoPixels from the Adafruit shop.
When everything is setup, click the Save settings button.
LED Layout
The LED Layout tab lets you configure where your NeoPixels are placed on the frame. As a result, you'll want to revisit this step after you finish assembling your frame.
You'll want to count how many pixels are going across the Top, Bottom, Left and Right sides of the frame. Enter each of those numbers into their respective boxes. The total needs to match the LED_COUNT value in your Pixel Trinkey Arduino code. If they don't then the NeoPixels will not light up.
The Input Position determines where the first NeoPixel (index 0 on the strand) is located. By default, it places it in the top left corner.
When everything is configured, press the Save Layout button to save.
Remember, the NeoPixel count in the Arduino script has to match the NeoPixel count in HyperHDR!
The Video Capturing tab is where you'll configure your USB capture card settings. To enable the capture card, check off Enable USB capture and then click Save settings.
Under the USB Capture section, you should be able to keep the default Automatic settings, but there are a lot of adjustable settings if you find you need to tweak anything.
Effects
The Effects tab lets you setup an LED effect that animates on boot. This can be handy to know that your HyperHDR instance is starting up correctly and its recognizing your serial device and NeoPixels.
Under Boot effect, check off the box next to Activate. Then, select a Type (Color or Effect) and then a color or Effect from the dropdown below that. You can adjust the Duration (in milliseconds) as well. When you're done, click Save settings.
On the Image Processing tab, go to the Smoothing section. Select Activate and Continuous output. Then click Save settings.
Scroll towards the bottom of the Image Processing tab and you'll see the Blackbar detector section. This is an optional setting, but it can be helpful if you watch a lot of movies with black bars at the top and bottom of the screen for different film aspect ratios. If you want to use it, select Activate and increase the Threshold to 15%. Then, click Save settings.
At this point, you should see your NeoPixels lighting up in correspondence with your connected display. You can see a live feed of your image capture by clicking on the little TV icon towards the top of the menu bar.
You can click the Live video button to see a live feed of what your capture card is seeing and what color the NeoPixels should be lighting up as.
If you aren't seeing the NeoPixels light up, you can go to the Logs tab and see a detailed log of what is happening with HyperHDR. Any errors, such as not seeing the Pixel Trinkey or having issues with mounting the USB capture card, will show up here to help you diagnose any problems.
You can check the status of USB devices on your Raspberry Pi with the lsusb command in the terminal. This will list the connected USB devices.
You can also restart the HyperHDR service on the Raspberry Pi if you're having problems. Use these commands:
sudo systemctl stop [email protected] sudo systemctl start [email protected]
Page last edited November 16, 2025
Text editor powered by tinymce.
