Install Tilecast Player

Install Tilecast Player

Tilecast Player runs on two kinds of device:

• Android TV devices — Fire TV, Google TV, and Android TV, without Google Play Services. Installed as an APK with package ID org.tilecast.player.
• Linux computers — 64-bit Intel or AMD machines with a graphical session. Installed as an AppImage.

Both builds pair, play, schedule, and update the same way. Pick your platform below. First-launch pairing is shared and described at the end of this page.

---

Android TV, Fire TV, and Google TV

Choose an APK

Published release

For a published release, download tilecast-player.apk from the repository's Releases page.

Release assets used by Tilecast's update system are:

• tilecast-player.apk
• tilecast-player-update.json
• tilecast-player-update.json.sig

Only the APK is installed directly on the TV. The JSON and signature are used by Tilecast Server to verify a release before deployment.

Local development build

From the repository root:

cd apps/player-android
./gradlew assembleDebug

The debug APK is written to:

apps/player-android/app/build/outputs/apk/debug/app-debug.apk

A debug build is for testing. Production update compatibility depends on preserving the Android signing identity used for the installed application.

Fire TV

Enable Developer Options and ADB debugging, note the Fire TV's LAN address, then run:

adb connect FIRE_TV_ADDRESS:5555
adb install -r tilecast-player.apk
adb shell monkey -p org.tilecast.player 1

For a local debug build, replace tilecast-player.apk with the path to app-debug.apk.

Fire OS menus and supported management features vary by model and firmware. Consumer Fire TV firmware commonly supports Standard Reliability but may not support device-owner Managed Kiosk.

Google TV and Android TV

Use wireless debugging, USB debugging, or another manufacturer-supported ADB connection:

adb devices
adb install -r tilecast-player.apk
adb shell monkey -p org.tilecast.player 1

Every action in Tilecast Player is designed for D-pad navigation. Verify focus and Back behavior with the actual remote.

Permission for future updates (Android)

Android and Fire OS normally require local approval before an app can install an APK.

After pairing, the commissioning wizard opens the appropriate Install unknown apps screen when update support is configured. Approve Tilecast Player, then return to the app.

Tilecast does not use ADB, simulated clicks, root, or hidden APIs to bypass the system installer.

---

Linux

This installs the published AppImage on an Intel or AMD Linux computer. The player needs a working graphical session and network access to the Tilecast server.

The automated release process publishes an x86_64 AppImage named tilecast-player.AppImage. That is the recommended format for Intel and AMD Linux signage computers. ARM and Raspberry Pi-class hardware can be evaluated with a source build, but there is no separately published or broadly validated ARM release yet — see Known Limitations.

Before you begin

You need:

• A 64-bit x86 Linux installation
• An X11 or Wayland graphical session
• A keyboard for initial setup, unless the server URL is supplied in advance
• The HTTPS or local HTTP address of the Tilecast server
• Permission in Tilecast Studio to approve and configure a screen

X11 is currently the simplest choice for unattended signage because live screen previews do not require the Wayland screen-capture portal.

Download and launch the AppImage

Download tilecast-player.AppImage from the latest Tilecast Player for Linux release, then place it in a permanent location:

mkdir -p ~/tilecast
mv ~/Downloads/tilecast-player.AppImage ~/tilecast/
chmod +x ~/tilecast/tilecast-player.AppImage
~/tilecast/tilecast-player.AppImage

Do not run the player as root.

AppImage or FUSE error

Some distributions do not install the compatibility FUSE library by default. On Debian or Ubuntu, install the available FUSE 2 compatibility package:

sudo apt update
sudo apt install libfuse2

On newer Ubuntu releases the package may be named libfuse2t64 instead.

For a temporary diagnostic run, AppImage can extract itself instead of mounting through FUSE:

~/tilecast/tilecast-player.AppImage --appimage-extract-and-run

Use the normal executable AppImage for a managed deployment. The extracted fallback is not the recommended self-update path.

Supply the server address without typing

Set the server URL before launch:

TILECAST_SERVER_URL=https://signage.example.org \
  ~/tilecast/tilecast-player.AppImage

The player validates and saves the address. The same value can be placed in the systemd service environment for unattended provisioning (see Reliability and Kiosk).

The command-line equivalent is:

~/tilecast/tilecast-player.AppImage \
  --server-url https://signage.example.org

Player data

By default, state and cached content are stored in:

~/.local/share/tilecast-player

This directory contains the installation identity, server address, credential, pairing state, cached manifest, downloaded media, configuration, command state, and watchdog state. Keep it when upgrading the AppImage.

To use another location:

TILECAST_DATA_DIR=/path/to/player-data \
  ~/tilecast/tilecast-player.AppImage

The player creates sensitive state files with owner-only permissions. Protect the entire data directory as a device credential store.

Environment variables (Linux)

Variable	Purpose
TILECAST_SERVER_URL	Server address; saved after first use
TILECAST_DATA_DIR	State and media-cache directory
TILECAST_LOG_LEVEL=debug	Verbose structured logs
TILECAST_WINDOWED=1	Disable kiosk fullscreen for testing
TILECAST_HW_DECODE=0	Disable Intel VA-API video decode
TILECAST_DISABLE_GPU=1	Force software rendering
TILECAST_MAX_FPS=30	Set the frame-rate cap
TILECAST_PREVIEW_SCREEN_CAPTURE=0	Disable framebuffer capture for live previews
TILECAST_PREVIEW_SCREEN_CAPTURE=1	Force framebuffer capture; Wayland may show a portal prompt

Build from source

A source build is useful for development and hardware evaluation. Node.js 22 or later and npm are required.

git clone https://github.com/Gibsonmb71/tilecast.git
cd tilecast
npm ci
npm run player:linux

Create local Linux packages with:

npm run player:linux:dist

Electron Builder writes the AppImage and Debian package under apps/player-linux/dist/.

A development run is not a managed AppImage, so Studio-driven AppImage replacement reports an unsupported installation mode. Use a packaged AppImage for update testing.

After first launch and pairing, configure the systemd service and kiosk session in Reliability and Kiosk.

---

First launch and pairing

On first launch, both builds:

1. Create a stable local installation identity.
2. Let you select a discovered Tilecast server or enter one manually.
3. Verify the server installation identity.
4. Create a short-lived pairing request.
5. Display a six-character code.

Continue with Pair a Screen.

Server address rules

• Public hostnames require HTTPS.
• Plain HTTP is accepted only for private IPv4 addresses, link-local addresses, localhost, and .local names.
• Explicit ports are preserved.
• The player never silently downgrades HTTPS to HTTP.

If LAN discovery fails, enter the URL manually. Discovery is only a convenience.

Do not claim support from installation alone

Installing successfully does not verify launch after power restoration, kiosk lockdown, standby and wake, HDMI input selection, unattended updates, or firmware-specific recovery.

Complete Reliability and Kiosk on every device model and firmware family — including the systemd and kiosk-session setup for Linux screens.