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. Install the APK with package ID org.tilecast.player.
• Linux computers: 64-bit Intel or AMD computers with a graphical session. Install the 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. Use this format for Intel and AMD Linux signage computers.

You can evaluate ARM hardware with a source build. Tilecast does not publish or fully validate a separate ARM release.

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.

Install from your Tilecast server

Your server publishes an installer for the release it has cached. On the signage computer, run:

curl -fsSL https://your-tilecast-server/install.sh | sudo bash

This installs the player for the kiosk account, points it at the server it came from, installs and enables the managed service with linger so it starts at boot, and provisions AirPlay support. The AppImage, its checksum, the service unit, and the UxPlay source archive come from your Tilecast Server. AirPlay build dependencies come from Debian package mirrors. The installer does not contact GitHub or another source-code host.

Re-running it upgrades the player in place.

Useful options:

Option	Purpose
--user NAME	Install for a specific kiosk account. Defaults to the account that ran sudo.
--create-user	Create the kiosk account if it does not exist.
--without-airplay	Skip AirPlay dependency provisioning.

If the installer reports that no Linux release is cached, open Settings → Player releases in Studio and download the newest Linux release, then run it again.

AirPlay provisioning never blocks the install. If it fails — usually no route to the Debian mirrors — the player still installs and pairs, and Studio reports which AirPlay dependency is missing. Add it later with:

curl -fsSL https://your-tilecast-server/install-airplay.sh | sudo bash

UxPlay 1.73.6 comes from a SHA-256-verified source archive embedded in Tilecast Server. The signage machine does not clone GitHub or contact another source-code host; it only needs the Tilecast server and normal Debian/APT mirrors.

Install by hand

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 --appimage-extract-and-run

Do not run the player as root.

FUSE-independent startup

Current Tilecast releases use a static AppImage runtime and do not depend on the older FUSE 2 compatibility library. The managed service also uses AppImage's supported --appimage-extract-and-run mode as a safety net for older artifacts and hosts where filesystem mounting is unavailable. The runtime still identifies the original artifact through $APPIMAGE, so signed Studio updates can replace it normally.

The managed service cleans stale AppImage FUSE mountpoints before each retry. This is intentionally limited to FUSE filesystems mounted below /tmp/.mount_*; it removes only empty directories after an unmount attempt.

Tilecast Linux Player 0.5.0 and older used the legacy runtime. If one of those releases reports a FUSE error, launch it with the managed command above once, then update to a newer release. Installing libfuse2 or, on newer Ubuntu releases, libfuse2t64 remains an alternative for legacy artifacts.

Do not manually unpack squashfs-root and run AppRun. This action removes the managed AppImage identity that updates require.

Supply the server address without typing

Set the server URL before launch:

TILECAST_SERVER_URL=https://signage.example.org \
  ~/tilecast/tilecast-player.AppImage --appimage-extract-and-run

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 \
  --appimage-extract-and-run \
  --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 --appimage-extract-and-run

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. The Player saves it 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 can 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 each device model and firmware family. For Linux screens, complete the systemd and kiosk-session setup.