How to add ambient lighting to your TV with Raspberry Pi

All tutorials

Make watching TV more immersive: you can extend the action on screen to the surrounding environment, and reduce eye-strain, with Raspberry Pi-powered ambient lighting. In this tutorial, we’ll talk you through setting up your LEDs, installing HyperHDR to your Raspberry Pi, and configuring your setup for the best ambient lighting experience.

What you’ll need

Shopping list

For the initial SD card setup, you’ll also need:

Another computer connected to your network. We’ll refer to this as “your usual computer”, to distinguish it from the Raspberry Pi computer that you are setting up as the ambient lighting controller.

Choosing the right Raspberry Pi and accessories

For this tutorial, we’ll be using a Raspberry Pi 3, and for this model, you will need a sacrificial micro-USB cable. We do not recommend using a Raspberry Pi Zero for this project.

Choosing a capture card

If you plan to watch content from streaming sites such as Netflix and Disney+, you’ll need a capture card that supports HDCP. Even if your input device(s) aren’t 4K, we’d also recommend future-proofing your setup by investing in a 4K capture card.

Choosing an LED strip

The size of your monitor will dictate the length of LED strip you need to purchase. To determine the length, measure all the edges of your monitor and add them together. For example, our 47” TV measures 106cm along the top and bottom, and 62cm either side. So we’ll need at least 336cm of NeoPixels. As strips are usually sold in metres, we ordered 4m and cut off the excess.

Choosing a power supply

The more LEDs you have, the more power you will need. To get an approximate measure of the output you’ll need to run your LED strip, use the following equation:

0.06 x LED quantity = output current

Our project uses 150 LEDs, so we’ll need approximately 9A power. As 9A isn’t a standard output current for off-the-shelf power supplies, and because we also need to power our Raspberry Pi, we’re using a 5V 10A barrel jack power supply for our setup.

Installing Raspberry Pi OS Lite

We’re going to use an application called Raspberry Pi Imager to write Raspberry Pi OS Lite to our microSD card. Raspberry Pi Imager is available for free for Windows, macOS, Ubuntu for x86, and Raspberry Pi OS. You can download it to your usual computer here.

Open Raspberry Pi Imager and connect your microSD card to your usual computer using a microSD card adapter. Now we can go ahead and install the operating system to the SD card. In Raspberry Pi Imager:

CHOOSE OS: the latest recommended version of Raspberry Pi OS Lite (32-bit) is available in the Raspberry Pi OS (other) dropdown menu.

Open the advanced menu: select the cog icon in the bottom right corner.

Set hostname: give your Raspberry Pi a name so you can find it on your network. For this tutorial, we’re going to name it “hyperhdr”.

Enable SSH: check the Enable SSH box and set a username and strong, memorable password.

Configure wireless LAN: enter the SSID and password for your network.

Select Save to close the advanced menu.

CHOOSE STORAGE: select your microSD card.

WRITE: click to write Raspberry Pi OS to your microSD card.

Once complete, you can remove your microSD card from your computer and insert it into your Raspberry Pi.

SSH into your Raspberry Pi

We’re going to SSH into the Raspberry Pi. SSH allows you to wirelessly connect to your Raspberry Pi, eliminating the need for a keyboard and mouse. It’s perfect if your Raspberry Pi is located in a hard-to-reach location, such as the back of your television.

To SSH into the Raspberry Pi, you’ll see the hostname set in Imager. If you have issues connecting using this method, you may want to use the Raspberry Pi’s IP address instead.

For more information in finding your IP address and remote accessing your Raspberry Pi, please visit our Documentation.

Connect via SSH

Open Terminal on your computer and run the following, replacing “username” with your previously chosen username and “hyperhdr” with your chosen hostname.

ssh username@hyperhdr.local

When asked for your password, use the password you created in Raspberry Pi Imager.

Install HyperHDR

We’re going to install HyperHDR, a fork of Hyperion that supports HDR. While not everyone using this tutorial will need HDR support, having this added benefit will future-proof your build with no loss of Hyperion functionality.

Now you’ve gained access to your Raspberry Pi, it’s best to check it’s up-to-date with the latest version of Raspberry Pi OS. To do this, enter the following into Terminal and press enter:

sudo apt update && sudo apt upgrade

Next, we need to download and install HyperHDR. HyperHDR is available for a variety of platforms. The following code will allow us to check the system and install the Raspberry Pi-specific software. Run the following script, entering Y when prompted.

wget https://github.com/awawa-dev/HyperHDR/releases/download/v17.0.0.0/HyperHDR-17.0.0.0-Linux-`uname -m`.deb
sudo apt install ./HyperHDR-17.0.0.0-Linux-`uname -m`.deb
sudo sed -i '/^User/d' /etc/systemd/system/hyperhdr\@.service
sudo systemctl daemon-reload
sudo service hyperhdr@pi restart
sudo service hyperhdr@pi status
The above script has been slightly edited from EverythingSmartHome’s original install script to include the recent version of HyperHDR. You can find the original script here.

Installation is complete when the following is displayed:

Connecting the hardware

Powering your LED strip

Your LED strip should be pre-wired with three wires: live, ground, and data. Ideally, they’ll be pre-installed into a connector, with additional live and ground wires, which we’ll be using to power the strip.

These two wires will likely be red and white, or red and black. Red is live, and white/black is ground. If required, strip them to expose 0.5cm of wire.

Next cut the USB-A end from your microUSB/USB-C cable. Depending on the type of cable, you’ll find either two or three wires inside. Again, these represent live and ground and, in some cases, data. As with the LED strip, strip 0.5cm of the live wire (usually red), and the ground wire (usually white or black).

Insert the live wire from the LED strip and microUSB/USB-C lead into the + hole of your female barrel jack connector and tighten them in place. Our connector uses a small screw to secure the wires. Next, insert the ground wire from the LED strip and microUSB/USB-C lead into the – hole of the connector and again tighten them into place.

Connect your LED strip to your Raspberry Pi

We’re going to use the GPIO pins of the Raspberry Pi to connect to the data wire of the LED strip. By default, HyperHDR is configured to connect to GPIO 18 and, though you can change this in the dashboard settings later, there’s no reason not to use GPIO 18.

GPIO 18 is the sixth pin down on the right hand side of your Raspberry Pi’s header pins.

You may also wish to connect a second wire between the ground wire of your LED strip and one of the GPIO ground pins to prevent your lights from flickering. For some setups, we’ve found this isn’t necessary, and for some it is. So, it’s better to be safe than sorry.

Attach the LED strip to your TV

Next, you need to line the rear edge of your monitor with the LED strip. Try to get them as close to the edge as you can without being visible from the front. When approaching corners, you can either cut your strip and solder wires to allow for the bend, use dedicated LED strip corner adapters, or simply fold the strip as shown. The latter is the easiest option, but remember to account for any ‘hidden’ LEDs later when we set up HyperHDR.

For ease, attach your LED in a clockwise direction when facing the monitor. If you attach them anti-clockwise, remember to select Reverse direction in the LED layout menu of HyperHDR later on in the process.

Connect your input device

Connect the USB port of your capture card to a USB port of your Raspberry Pi using a USB-to-USB cable.

Connect the capture card’s HDMI OUT port to your monitor using an HDMI-to-HDMI lead.

Lastly, connect your input device (games console, DVD Player, TV receiver) to the capture card’s HDMI INPUT port using the second HDMI to HDMI lead.

Multiple input devices (optional)

If you have more than one device you wish to input into your TV, you can use an HDMI hub. Plug all your devices into the hub and connect the hub’s HDMI OUT port to the HDMI IN port of the capture card.

Once everything is plugged in, connect your power supply to the barrel jack connector. Your setup is now complete, and we recommend tidying up your wires and securing everything to the back of your TV, or into a ventilated container.

Configure HyperHDR

Next, we’re going to use the HyperHDR dashboard to configure the setup for your monitor.

Open a browser window on your computer and the following into the address bar, replacing “hyperhdr” with your chosen hostname:

hyperhdr:8090

The HyperHDR dashboard will open in the browser window. If it does not, check your network connection and restart your Raspberry Pi.

LED Hardware

Our first step is to tell HyperHDR what type of LEDs we have, and how many there are. Select LED hardware in the side menu. This should open up the LED controller menu.

There are many different types of LED controllers on the market. We’re using a ws2812B LED strip, as it’s a good balance between functionality and cost. So we’re going to select “ws281x” from the Controller type dropdown menu.

Once you’ve selected your controller type, you need to enter the number of LEDs on your strip in both the Hardware LED count and Maximum LED count boxes. Confirm your jumper wire is connected to GPIO 18 and that 18 is selected in the GPIO number box, and then click Save settings.

Next, select LED layout at the top of the page.

Here, we need to tell HyperHDR where our LEDs are. Enter the number of LEDs for the top, bottom, and sides of your monitor into the appropriate boxes. You’ll also want to move the input indicator to the correct position. Ours is located at the bottom of our television.

Ideally, you’ll have attached your LEDs in a clockwise direction. If not, now is the time to select Reverse direction.

Click Save layout.

Video capturing

Select Video capturing from the side menu.

Your capture card should show in the Device dropdown menu of the USB capture menu. If it doesn’t, try restarting the Raspberry Pi and waiting a few minutes.

Select your capture card and save settings at the bottom of the menu.

Select Enable USB capture under Instance USB capture menu and save settings at the bottom of the menu.

Image processing

Select Image processing from the side menu.

Scroll down and activate Blackbar detection and Save settings.

RGB order wizard

Lastly, we’re going to make sure HyperHDR is aware of the RGB order of your LED strip. Select Advanced from the side menu, followed by Misc and RGB order wizard. Here, you’ll need to tell HyperHDR whether the colours on the screen match the colours of your LEDs. In our case, they were reversed.

Completing the process

After following the steps of this tutorial, you should see your LED lights reacting to the video content on your television. If you don’t, go back and double-check the steps to ensure you followed them correctly.

Chances are that you’ll need to tweak the settings to get the best experience from your LEDs. We found that we needed to move the input location a few LEDs in the LED layout section to match our lights to the images on the screen. And, for those of you with a taste for colour theory, HyperHDR offers a variety of more advanced options. To access them, select Advanced from the side menu, followed by Misc and Settings level. Here, you can select Expert to access all HyperHDR features in the dashboard.

Help and support

For support with Hyperion settings and issues, please visit the Hyperion forums. For HyperHDR specific queries and to submit issues with the software, visit the HyperHDR GitHub repo.

For support with official Raspberry Pi products, please visit the Raspberry Pi Forums.