Set up a Raspberry Pi player

A Raspberry Pi is a small, cheap computer that can sit behind the TV and run the CastWize player. These steps show how to install it, pair it and make it come back by itself after a power cut.

Read this first

• We haven't tested the Pi player on real Raspberry Pi hardware yet. It is built for the Pi's 64-bit system, but test it with your own content before you mount the screen.
• Video is decoded in software, not by the Pi's video chip. Images, text and widgets are light work. A single 1080p video may be fine. Heavy 4K video, or several videos at once in different zones, may not play smoothly. If your playlist is mostly video, an Android TV box or a small Windows PC is the safer choice.
• Updates are manual for now: download the newer player from the support page when one comes out.

What you need

• A Raspberry Pi 4 (4 GB or more), Pi 400 or Pi 5. Older boards such as the Pi 3 aren't recommended.
• 64-bit Raspberry Pi OS with the desktop, installed and connected to the internet. Wired Ethernet is the most reliable.
• A keyboard and mouse for the setup, and a TV with HDMI.

Steps

1. Install two libraries the player needs. Open a terminal on the Pi and run:

   sudo apt install libfuse2 zlib1g-dev

   You only do this once.
2. Download the player. On the Pi, open the support page and click Download for Raspberry Pi. You get a file named like CastWize-Player-X.Y.Z-arm64.AppImage, where X.Y.Z is the version number. Use your real file name in the commands below.
3. Make it runnable. In the terminal, go to the folder you saved it in and run (with your file name):

   chmod +x CastWize-Player-X.Y.Z-arm64.AppImage

   It's a good idea to keep it somewhere permanent, such as your home folder, rather than Downloads.
4. Run it. Double-click the file or run it from the terminal with ./ in front of the name. The player opens full screen and shows a pairing code.
5. Pair it. In CastWize Studio, go to Screens, click Add screen and type the code. See Pair a screen.
6. Log in automatically. Run sudo raspi-config, open System Options, then Boot / Auto Login, and choose Desktop Autologin.
7. Make the player start at login. On its first run the player adds a start-up entry, ~/.config/autostart/CastWize Player.desktop. Open it in a terminal editor with nano "$HOME/.config/autostart/CastWize Player.desktop" and make sure the Exec= line points at your AppImage file, for example:

   Exec=/home/pi/CastWize-Player-X.Y.Z-arm64.AppImage

   (Use your own user name and file name.) If the line shows a path starting with /tmp/, replace it: that path disappears after a restart.
8. Restart the Pi and check. Run sudo reboot. The Pi should log in, open the player full screen and carry on with the playlist without a new pairing code.

The player asks for a new pairing code after every restart. Why?

The player keeps its login in the system keyring. A Pi set up without a desktop keyring has nowhere to keep it. Install one with sudo apt install gnome-keyring, restart, and pair again.

Will the screen go blank or to sleep?

The player asks the system to keep the display awake while it runs. If your screen still blanks, turn off Screen Blanking under Display Options in raspi-config.

What happens if the internet drops?

Images and videos are stored on the Pi (up to 500 MB), so the screen keeps playing through a Wi-Fi drop. Web pages, YouTube and Google widgets need the connection. If the Pi restarts while the internet is down, it plays the last content it had saved, and catches up once it reconnects.

Can I reboot the Pi from Studio?

Not with the default setup. Remote reboot on desktop players is off unless the player is started with the setting CASTWIZE_ALLOW_REBOOT=1, and the Pi user must be allowed to run reboot without a password. You can add the setting to the start-up entry: Exec=env CASTWIZE_ALLOW_REBOOT=1 /home/pi/CastWize-Player-X.Y.Z-arm64.AppImage. This hasn't been tested on a real Pi. Refresh in Studio works without it.