Set up the ParallaxTV Hub

For ParallaxTV Pro · runs in Docker on a computer or NAS · Help with the TV app

The Hub is an optional companion to the TV app. You don’t need it to use ParallaxTV. It runs on a computer or NAS that stays on, on the same home network as your TVs, and adds a few things the TVs can’t do on their own. It needs a Pro license, and it uses one of the license’s five TV slots. Setting it up takes about 15 minutes.

On this page: What it does · What you need · 1. Install Docker · 2. Find the address · 3. Install the Hub · 4. Check it · 5. Pair your TVs · Folders · Other apps · Update and back up · Troubleshooting

What it does

What you need

Step 1. Install Docker

The Hub runs inside Docker, free software that keeps it separate from everything else on the computer. If Docker is already installed, skip to step 2.

Windows

  1. Download Docker Desktop and run the installer. Keep the option to use WSL 2 ticked. Restart when asked.
  2. Open Docker Desktop and wait until it says the engine is running.
  3. Under Settings › General, tick “Start Docker Desktop when you sign in”, so the Hub comes back after a restart.

Mac

  1. Download Docker Desktop for your Mac (Apple silicon or Intel), open it, and drag Docker to Applications.
  2. Open Docker from Applications and wait until it says the engine is running.
  3. Under Settings › General, tick “Start Docker Desktop when you sign in”.

Linux and Raspberry Pi

In a terminal:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Then sign out and back in, so you can run docker without sudo. On a Raspberry Pi, use the 64-bit Raspberry Pi OS; the 32-bit one can’t run the Hub.

Synology NAS

Open Package Center and install Container Manager (on DSM 7.2 and later; older versions call it Docker). You’ll create the Hub from Container Manager in step 3.

QNAP NAS

Open App Center and install Container Station.

Unraid

Docker is built in. From the Apps tab, install the Compose Manager plugin, which step 3 uses.

Step 2. Find the computer’s address

The TVs reach the Hub at this computer’s address on your home network, something like 192.168.1.20. Find it now; step 3 needs it.

WindowsOpen Command Prompt, run ipconfig, and look for “IPv4 Address” under your Wi-Fi or Ethernet adapter.
MacSystem Settings › Network › your connection › Details, or run ipconfig getifaddr en0 in Terminal.
Linux, Raspberry PiRun hostname -I; the first address is the one.
NASThe address you open its control panel at, or its network settings.

The address can change when the router restarts. To stop that, reserve it for this computer in your router’s settings (often called a DHCP reservation or fixed IP). Otherwise, if the TVs lose the Hub one day, look up the address again and pair them again.

Step 3. Install the Hub

On a computer (Windows, Mac, Linux, Raspberry Pi)

  1. Open a terminal: PowerShell on Windows, Terminal on a Mac or Linux.
  2. Make a folder for the Hub and download its settings file. Its settings and your channels are kept in this folder. 
    mkdir parallaxtv-hub
cd parallaxtv-hub
curl -O https://parallaxtv.app/hub/compose.yaml
    Or download compose.yaml in your browser and move it into a new parallaxtv-hub folder.
  3. Open compose.yaml in a text editor (Notepad, TextEdit or nano) and change these three lines. Keep the spaces at the start of each line exactly as they are.
    PXTV_LICENSE_KEYYour Pro license key.
    PXTV_HOSTNAMEThe address from step 2.
    TZYour TVs’ time zone, such as America/New_York, America/Chicago, America/Denver, America/Los_Angeles, Europe/London or Australia/Sydney (full list). Every channel’s day starts at a local hour, so this keeps the Hub in step with your TVs.
    For example: 
          PXTV_LICENSE_KEY: PXTV-AB12-CD34-EF56-GH78
      PXTV_HOSTNAME: 192.168.1.20
      TZ: America/Chicago
  4. Save the file, then start the Hub from the same folder: 
    docker compose up -d
    The first time, it downloads the Hub (about 260 MB). When it prints Started, go to step 4.

On a Synology NAS

  1. In File Station, make a folder for the Hub, for example docker/parallaxtv-hub.
  2. Open Container Manager › Project › Create. Name it parallaxtv-hub, choose that folder as the path, and choose “Create docker-compose.yml”.
  3. Paste in the contents of compose.yaml and change the three lines described above.
  4. Choose Next, then Done. Container Manager downloads and starts the Hub.

On a QNAP NAS

  1. Open Container Station › Applications › Create.
  2. Name it parallaxtv-hub, paste in the contents of compose.yaml, and change the three lines described above.
  3. In the volumes lines, change ./data to a full path on the NAS, such as /share/Container/parallaxtv-hub/data, so the Hub’s settings are kept in a folder you can find.
  4. Choose Create.

On Unraid

  1. In the Docker tab, under Compose, choose Add New Stack and name it parallaxtv-hub.
  2. Edit the stack, paste in the contents of compose.yaml, and change the three lines described above. Change ./data to /mnt/user/appdata/parallaxtv-hub.
  3. Choose Compose Up.

Step 4. Check that it’s working

On any computer or phone on the same network, open http://<address>:8642 in a browser, for example http://192.168.1.20:8642. You should see the Hub’s page with:

Step 5. Pair your TVs

  1. On the TV, open Settings › ParallaxTV Hub.
  2. Enter the Hub’s address, such as 192.168.1.20, and choose Next.
  3. Enter the 6-digit code from the Hub’s page, and choose Pair.

A code works once. It changes every 15 minutes, and after 5 wrong tries, so if it’s refused, reload the Hub’s page for the current one. Pair each TV the same way.

Add your folders

To use folders, tell Docker where they are, then tell the Hub. Both steps are needed.

  1. In compose.yaml, under volumes, remove the # in front of the lines you want and change /path/to/… to your real folders. On Windows, write a folder as C:/Users/you/Videos/Movies. The part after the colon is where the Hub sees the folder; leave it as it is.
  2. In the Hub’s folder, open the data folder, create a file named config.yaml, and list the folders: 
    libraries:
  - id: movies
    name: Movies
    path: /media/movies
    type: movie
  - id: tv
    name: TV Shows
    path: /media/tv
    type: show

interstitials:
  - id: commercials
    path: /media/interstitials
    Leave out any you don’t use.
  3. Restart the Hub so it reads them (it reads its settings only when it starts): docker compose up -d --force-recreate. On a NAS, stop and start the project.

Movies can be anywhere in their folder, one file each, named like Alien (1979).mkv. TV shows need a folder per show, with the season and episode in each file name, such as Red Dwarf/Season 1/Red Dwarf - S01E01.mkv. Genres, years and ratings come from Kodi-style .nfo files next to the videos. Without them, library and show channels work, but genre and mood channels won’t find those videos.

Commercials: MP4, MKV, MOV or WebM clips of up to 10 minutes, in formats your TV can play. They appear on the TV under a channel’s Commercials › Clips from, marked “· Hub”. After adding clips, use Settings › ParallaxTV Hub › Rescan folders on a TV. New files are noticed a few seconds after they’re copied in.

Watch your channels in other apps

These streams are converted on the Hub’s computer as they play: about one CPU core per channel being watched, and 3 at once unless you change it.

Update, back up, remove

Troubleshooting

First, see what the Hub itself says: from its folder, run docker compose logs hub (on a NAS, open the container’s log). The last lines usually name the problem.

Installing

“docker: command not found” or “not recognized”Docker isn’t installed or isn’t running. On Windows and Mac, open Docker Desktop and wait until the engine is running, then try again in a new terminal window.
“permission denied” connecting to the Docker daemon (Linux)Sign out and back in after usermod, or put sudo in front of the command.
“port is already allocated”Something else uses port 8642. In compose.yaml, change both numbers in '8642:8642' to a free port, such as '8650:8650', add a line PXTV_PORT: 8650 under environment, and on the TV type the address with that port, such as 192.168.1.20:8650.
“no matching manifest” or “exec format error”The computer is 32-bit. On a Raspberry Pi, install the 64-bit Raspberry Pi OS.
“yaml: line … did not find expected key”A line in compose.yaml lost its spaces. Download it again and change only the values after the colons.

The Hub’s page

The page won’t openCheck the address and the :8642. Check the Hub is running: docker compose ps should show it “Up”. On Windows, when first asked, allow Docker through the firewall on private networks; on Linux with a firewall, run sudo ufw allow 8642/tcp.
License: “Not active” or “No license key configured”Check the key in compose.yaml (copy it from the email; it starts with PXTV-), then run docker compose up -d again.
“Already used on 5 TVs”The Hub counts as a TV. Free a slot on a TV you no longer use (Settings › License › Deactivate this TV), or email us.
License: “offline grace period”The Hub can’t reach the internet. It keeps working for up to 30 days on its saved license; check the computer’s connection, and it renews by itself.
The time or time zone is wrongSet TZ in compose.yaml to your TVs’ zone and run docker compose up -d.

Pairing and the TVs

“The Hub did not answer”The TV and the Hub’s computer must be on the same network: not a guest Wi-Fi, and not with a VPN running on the computer. Check that the page from step 4 opens on a phone on the TV’s Wi-Fi, and that PXTV_HOSTNAME is that same address.
The code is refusedCodes change every 15 minutes and after 5 wrong tries. Reload the Hub’s page and use the code shown now.
It worked, then the TVs lost the HubThe computer’s address probably changed. Find it again (step 2), update PXTV_HOSTNAME, run docker compose up -d, and pair the TVs again. Reserving the address in your router stops it happening again.
Folders don’t show on the TVCheck both halves of Add your folders: the volumes line in compose.yaml and the entry in data/config.yaml, then restart the Hub. The log names any folder it can’t read. Then use Settings › ParallaxTV Hub › Rescan folders on the TV.
A show is missing, or episodes are skippedEpisode files need the season and episode in their names (S01E02 or 1x02), or a Season 1 folder. The log lists every file it skipped.

Streams in other apps

A stream stutters or stopsThe computer is too slow for that many at once. Watch fewer channels in other apps at the same time, or use a faster computer.
A fourth channel won’t startThe Hub streams 3 channels at once by default. Close one, or raise maxConcurrent under stream in data/config.yaml if the computer can handle more.
Plex or Jellyfin doesn’t find the tunerAdd it by address instead, as in Watch your channels in other apps, and make sure the media server can open the Hub’s page.

Still stuck?

Email support@freeradicalsgroup.com with what you tried and the last lines of docker compose logs hub. A person reads every message.