How to set up HyperHDR? Part I: basic configuration

Navigate to the section:

• Introduction
  
• Setting up the video grabber
  
• Configuring adalight USB LED strip on the primary instance
  
• Configuring smoothing and color calibration
  
• Creating an additional instance for other light source
  
• Setting up the Philips Hue device
  
• Configuring and enabling sound visualization effects
  
• Remotely controlling HDR tone mapping
  
• Logs are your best friend
  

Introduction

For the tutorial in this chapter I connect to HyperHDR installed on Raspberry Pi 4 from Apple macOS. But the steps are almost the same for other OS. From version 16 you can have HyperHDR installed on the macOS as an alternative if you are interested. Ezcap 269 is used as a grabber.

To make this tutorial a bit more challenging I will configure two instances of leds: classic sk6812 LED strip on the back of TV and remote instance of Philips Hue lamps. Both will be used at the same time to make deeper ambient lighting immersion. Of course you may use just one instance with a LED strip and skip a part for the second instance.

OK, let's start. Connect with the HyperHDR with the address:

http://IP_OF_HYPERHDR:8090

For the configuration phase please DO NOT USE https instance available at port 8092 because some WWW wizards won't work (the browser security protection for https channel blocks non-encrypted communication with other devices).
You can use https later when everything is set up.

As you can see there is warning about setting new password so it's good to do it now or later.

Setting up the video grabber 

You grabber should be available now with default settings.
Click TV icon in the upper right corner to turn on video preview.

Now turn on video stream clicking on the 'Live video' button.

Success! We've captured video stream from the grabber. But something is wrong...You have noticed that the colors are washed-out and overall luminescence is low? That's because we have captured a HDR10 video stream and almost none of USB grabbers can process HDR metadata so important part of information about the image is lost. But we can do something about it later. Go to the Capturing hardware tab.

 

First select a video device from a list. Then you can set up resolution and refresh rate. I think max useful resolution is 720p. For most setups 480p is sufficient (only when no decimation/image size reduction is applied).

You need decent LED strip controller to have any use of 60 frames per seconds from the grabber such as direct SPI/PWM connection from Rpi or USB driver like HyperSerialWLED or HyperSerialEsp8266. If you plan to use it only for a network/WiFi controller instance or for an Arduino with over 150 leds in the led strip then you can let it go: it won't work well.

Let's fix our broken HDR video stream now. Click on the 'HDR to SDR tone mapping' button and save it. We have our colors back :-)

Other most import options are:

• "Quarter of frame mode" it scales the video stream to (1/2 width x 1/2 height) size. Useful on slower devices and for a grabber that doesn't allow changing resolution like Rullz Navy U3 that sticks to the 1080p capture resolution (which we don't need) for most time.
  
  
• "Software frame skipping" if the grabber minimal 30 FPS is too much for you or your hardware then you can reduce the refresh rate in the software. If you set it to n then every n-th frame from 30FPS will be processed. For example set it to 5 and as a result final refresh rate (for a grabber 30FPS) will be 30/5 = 6 FPS.
  
  
• "Force encoding format on the grabber" most grabbers like popular MS2109 are capable of providing at least 2 or more video encoders. MS2109 provides MJPEG and YUV for lower resolutions and refresh rates and only MJPEG for higher resolutions like 1080p. The settings allows you to set desired format for a grabber. MJPEG has a higher CPU demand so you should avoid it especially on Raspberry Pi 1 or Zero. YUV has greater demand for a USB bandwidth so higher resolutions will work only for grabbers with real (not just with connectors painted in blue) USB3.0/3.1 port & hardware interface.
  

Configuring USB adalight LED strip on the primary instance

Now it's time to set up our primary instance for our LED strip behind the TV.

The LED strip is controlled by USB high-speed HyperSerialWLED/HyperSerial8266. So go to the LED devices and select 'LED hardware' tab then adalight from the list.

For HyperSerialWLED/HyperSerial8266 enable AWA protocol and set 2000000 speed.

If you are using classic USB Adalight driver like legacy Arduino sketch (not recommended!) set AWA protocol OFF and speed can be 500000 max depending on the Arduino sketch and capability. Above that speed you will meet serious troubles from time to time.

Proceed to the LED strip geometry definition. Switch to 'LED Layout' tab in the same window.

Let's assume that we have 50 leds on the top, 20 leds on both sides and 40 leds on the bottom because there is a 10 led gap for TV stand. Like on the following picture. 

So set it up in the following dialog. Even if you have less than 50 leds at the bottom segment set it to 50 as the gap takes the missing rest.

We have set up our LED layout but something is still wrong as on the above screenshot. The input in the HyperHDR doesn't match the real one at the bottom and the gap is at wrong place. You must set also gap & input position to make it right. They are equal to: top+left or right+A segment (diagram) so: 50 + 20 + 20 = 90.

That's better. If you have setup opposite to the clock, set 'Reversed direction' option enabled.

Configuring smoothing and color calibration

One of most important option in HyperHDR is Smoothing because almost no one likes sudden burst of light from the LED strip. It's available in the 'Image processing' tab.

Default options should be proper for most users. But if you are using not recommended and slow LED strip driver like Arduino then 80Hz refresh rate from the screen above is probably a way too much. For example typical 60 led/meter led strip for a 55" TV that it's driven by the Arduino has only just over 20Hz pathetic refresh rate.

WLED 0.12 (and HyperSerialWLED/HyperSerial8266) has a built-in benchmark so you can test the real performance on your own but first enable 'continues output' and set high refresh rate to measure it on device. For everyday usage you should disable 'continues output'.


From version 16 there is important anti-flickering filter. Without it you may experience disturbing subtle flickering on the dark scenes. It's caused by the video source or video player aggressive dithering with a combination of high refresh rate on the LED strip. It's detailed described on the configuration page.

You can see how the problem manifests on the following clip and how is resolved on the second one when anti-flickering filter is enabled with relaxed settings: threshold = 32 and minimal step = 2 (you may need to increase it on your system) . Capturing video at such conditions is a difficult task for the phone camera to maintain colors but at least luminescence's changes are visible on these samples. New smoothing algorithm 'Alternative Linear' was used. It was introduced in v16 and it is similar to the standard 'Linear' but at the end of transition the decay effect is reduced.

Flickering appears at 00:07 and at the 00:18

and the flickering issue is resolved on the same video source with new anti-flickering filter:

Because streamable service can reduce quality during the processing here are direct links to the video's downloads:
Download flickering clip at ufile.io
Download antiflickering clip at ufile.io

On the same section there is a 'Color calibration' panel:

Most important options are: 3 gamma's, 'Backlight threshold' and 'Colored backlight'.

• 'Red/green/blue gamma' decides about intensity/gain of each color channel.
  
  
• 'Backlight threshold' is minimal gray backlit of your led strip so it won't turn OFF causing flickering.
  
  
• 'Colored backlight' tries to preserve a part of original color to set backlit instead of gray.
  

Probably you want to have backlight enabled as 'Smoothing/Anti-flickering filter' works best with 'Colored backlight' enabled and 'Backlight threshold' set to 2-3 depending on your LED setup and needs.

Creating an additional instance for other light source

We have finished configuration of our primary instance. Now we'll create a secondary instance for our other light source. Go to the 'General' tab, provide 'New instance name' and click the button to create new instance.

New instance for our Philips Hue lamps is created.

Now you have to start it.

This is a very important step:
you must switch to the new instance in the upper-right corner before proceeding further. Otherwise you will just override your primary instance with new settings.

Setting up the Philips Hue device

Go to the 'LED hardware' and select 'philipshue' from the list.

Before proceeding you must create an 'Entertainment group' for your lamps in the Philips Android or IOS mobile application. Don't even try without doing it first. Your Hue Bridge should also to be working for at least 2-3 minutes to avoid connection problems during configuration at startup. You should try first to send a color from the Philips mobile app to make sure it's working and your 'Entertainment group' is created.

Then start a wizard in HyperHDR.

HyperHDR should find the Philips Hue bridge in the same sub-network. Some custom router's firewall rules or enabling WiFi isolation can cause the process to fail.

Click the 'Create new user and and clientkey' button.

Now it's time to click a large hardware button located on your Hue bridge. It allows to authorize the HyperHDR's access. If everything goes OK you should have the Username and Clientkey filled in automatically. Identificator of 'Entertainment group' should also be found automatically.

Proceed with clicking the 'use group...' button.

Now you can assign area of the TV to single, selected lamp in the entertainment group. Because I have 2 lamps on the floor (one just on the right of the TV and second to the left) I selected following options.

Configuring and enabling sound visualization effects

One of unique HyperHDR feature is sound visualization on your ambient ecosystem. Digital capture devices are preferred as there is no analog sound filter at input available in the current version. To make it work you must make sure that the grabber receive audio stream. Be aware that some amplifiers like Denon can block it in typical configuration (use of ARC/EARC is necessary then).

Let's configure the hardware first in the 'Effect' tab. On the following screen I selected Ezcap 269 device. Do not confuse it with some other system devices.

Next we need to enable 'Activate' option and save our settings.

Navigate to the 'Remote control' tab and turn on video preview to verify result.

For the beginning use 'Equalizer' from the list to test if everything works OK.

If you activated & set up your grabber correctly and it receives a audio stream you should see jumping equalizer's bars.

If they are flat something is wrong. In 99% cases your grabber doesn't receive a sound. Navigate to the 'Logs' tab to confirm it. Otherwise you can have fun with other music effects. See them in the video visualizer to know how they work.

Let's see the logs...

It's a final confirmation: you have enabled some audio device and it works but it provides no sound...only silence. Maybe you've selected wrong device but more probably there is no sound on the grabber's input.

Remotely controlling HDR tone mapping

You can remotely control the HDR tone mapping state using for example Home Automation system. If you are using Home Assistant and Denon amplifier, it's possible to automatically switch it depending on the actual video stream format (example).

Version 16 allows using simply GET requests.

Turning HDR tone mapping OFF:

http://IP_OF_HYPERHDR:8090/json-rpc?request={%22command%22%3A%22videomodehdr%22%2C%22HDR%22%3A0}

Turning HDR tone mapping ON:

http://IP_OF_HYPERHDR:8090/json-rpc?request={%22command%22%3A%22videomodehdr%22%2C%22HDR%22%3A1}

Getting HDR tone mapping state (search for videomodehdr property):

http://IP_OF_HYPERHDR:8090/json-rpc?request={%22command%22%3A%22serverinfo%22}

Logs are your best friend

In case of any trouble (not necessary related to the sound capturing) first refer to the log.

For example on the following screenshot you can find information about misconfiguration in the adalight device section (serious errors are mostly in red) and video performance stat in the last line. Performance statistics are refreshed every one minute and it provides you important information about how your system performs and if it's necessary to reduce video capturing resolution.