# Put the Player on your screen
> Canonical HTML: https://screenrig.ai/docs/players
Install the screenRIG Player on the screen, keep it running, and let your agent publish the content. The same Player shows ordinary content and paid advertising for accounts that opt in; buyers pair nothing.
## Which Players are available?
Players: the Player web app (PWA), Android on Google Play, Amazon Signage Stick, Apple TV, macOS, Windows, Linux and Raspberry Pi packages, BrightSign, and Samsung Smart Signage (Tizen). [Install a native Player](https://screenrig.ai/docs/players.md#native) for the fastest, most reliable playback.
The Player web app (PWA) at [play.screenrig.ai/player/](https://play.screenrig.ai/player/) runs on any screen with a modern browser: a smart TV or commercial display with a built-in browser, a managed ChromeOS device in [kiosk mode](https://screenrig.ai/docs/players.md#chromeos), a tablet, or a computer plugged into the screen. A status-only embed of the Player is at [play.screenrig.ai/player/embed/status/](https://play.screenrig.ai/player/embed/status/).
Every Player shows a pairing code. Give it to your agent, and it takes it from there.
## Primitive support by platform
Compare the six content primitives across Player platforms.
| Player platform | Image | Video | Stream | Iframe | Application | Card |
| --- | --- | --- | --- | --- | --- | --- |
| Web / PWA | Yes | Yes | HLS | Yes | Yes | Yes |
| Android (`standard`) | Yes | Yes | HLS + RTSP + multicast¹ | Yes | Yes | Yes |
| Android (`amazon` flavor) | Yes | Yes | HLS + RTSP + multicast¹ | Yes | Yes | Yes |
| Linux (Qt, x86_64 artifact) | Yes | Yes | HLS + RTSP + multicast¹ | Yes | Yes | Yes |
| macOS | Yes | Yes | HLS | Yes | Yes | Yes |
| Apple TV / tvOS | Yes | Yes | HLS | No | No | Yes |
| Windows | Yes | Yes | HLS | Yes | Yes | Yes |
| BrightSign | Yes | Yes | HLS | Yes | Yes | Yes |
¹ Direct UDP/MPEG-TS multicast is optional and must be enabled on Android or Qt. It requires a network that carries the multicast group to the Player. Other Players use HLS; a multicast source can include an HLS alternative.
Apple TV supports images, video, HLS streams, and cards. It cannot display iframe web pages or packaged web applications. A playlist containing either web primitive is rejected; the last accepted playlist stays active.
An iframe `src` can be any YouTube video, Shorts, live, playlist or `youtube.com/channel/UC…/live` link. screenRIG stores it as an embed that autoplays, loops and hides YouTube's controls. Native Players play it with sound and the Player web app plays it muted; add `mute=1` to the link to mute it everywhere.
Every Player platform above also plays the playlist soundtrack. The Player web app starts it once the browser allows sound; see [Soundtracks](https://screenrig.ai/docs/players.md#soundtrack).
## Eventual sync
Android, Amazon Signage Stick, macOS, Windows, Linux and Raspberry Pi Players gradually align page changes with nearby Players showing the same playlist revision. Assign the same playlist to screens on one IPv4 subnet. Use fixed page durations of at least one second, cut transitions and no entrance animations. Each Player broadcasts one small page-start beacon and makes a tiny adjustment to its wait before the next page. Timing adjustments activate only after a second Player on that same playlist revision is discovered. Screens on different playlists do not influence one another. A lone screen keeps its normal playback timing; the group follows the median playback position once peers join.
The network must allow device-to-device UDP broadcast on port 49817. Allow local-network access when the device asks. Screens keep playing through packet loss, power cycles and network partitions, and converge again as page beacons arrive. Each added wait is capped at 40 milliseconds. Long pages and large timing differences take longer to converge; this synchronizes page changes rather than video frames or soundtracks.
To bring a location close together quickly, ask your agent to restart playback on its screens with `screen reload --tag LOCATION`, replacing `LOCATION` with their shared tag. The Players restart eligible playlists at the first page and finish alignment through their regular beacons. Pairing and downloaded content stay in place.
## Install a native Player
| Platform | Get the Player |
| --- | --- |
| Android TVs, tablets, and signage boxes (Android 9 or later) | [Google Play](https://play.google.com/store/apps/details?id=ai.screenrig.player) or the [Android APK](https://screenrig.ai/docs/players.md#android-apk) |
| Amazon Signage Stick and Fire TV Sticks | [Amazon Appstore](https://www.amazon.ca/TelemetryTV-ScreenRIG-Player/dp/B0HJF59T8M) |
| Apple TV | App Store |
| macOS | [Mac App Store](https://apps.apple.com/us/app/screenrig-signage/id6813182055) |
| iPhone and iPad | [App Store](https://apps.apple.com/us/app/screenrig-signage/id6813182055) |
| Windows | [Microsoft Store](https://apps.microsoft.com/detail/9n4pkwgz2jkj?hl=en-US&gl=CA) |
| Linux (x86_64) | [Linux package](https://screenrig.ai/docs/players.md#linux) from screenrig.ai/linux/ |
| Raspberry Pi (64-bit) | [Linux aarch64 package](https://screenrig.ai/docs/players.md#raspberry-pi) from screenrig.ai/linux/ |
| Samsung Smart Signage (Tizen) | Native Player |
| BrightSign | [screenrig.ai/brightsign/](https://screenrig.ai/brightsign/) |
Every download is also on the [Downloads page](https://screenrig.ai/downloads.md).
1. Install the Player for your screen device.
2. Launch it. It opens full screen and shows a pairing code.
3. Give the pairing code to your agent. It pairs the screen and publishes to it.
Each native Player downloads media once, caches it, and replays it from local storage.
## Install the Android APK
Use the APK on Android TVs, Google TV devices, tablets, and signage boxes on Android 9 or later that do not use Google Play. Use it when you install by ADB.
The APK is signed and public. It is the same Player as the Google Play build. Its file name carries the version, so use https://screenrig.ai/android/manifest.json as the only pointer to the current file.
Before you start, turn on developer options and USB debugging or network debugging on the device. You also need `adb` on your computer.
1. Connect to the device. For a network device, run `adb connect DEVICE_IP:5555`.
2. Download, check, and install the APK:
```sh
curl -fsSL https://screenrig.ai/android/manifest.json -o manifest.json
path=$(jq -r .player.path manifest.json); sha=$(jq -r .player.sha256 manifest.json)
curl -fsSLO "https://screenrig.ai$path"
echo "$sha ${path##*/}" | sha256sum -c -
adb install -r "${path##*/}"
adb shell am start ai.screenrig.player
```
3. The Player opens full screen and shows a pairing code. Give the code to your agent.
### Start at boot
**Start on boot** is on by default. It is a switch in the Player operator settings: once the screen is paired, press OK on the remote to open the menu and choose **Settings**. On Android 9, no permission is needed. On Android 10 and later, grant **Display over other apps** unless the device is device-owner managed: select **Start on boot** and follow its prompt. Where a permission screen is available, the Player asks when it first shows its pairing code: select **Open settings** and allow **Display over other apps**. Until the permission is granted the row reads **Permission required** and the Player does not start at boot. You can also grant it with ADB:
```sh
adb shell cmd appops set ai.screenrig.player SYSTEM_ALERT_WINDOW allow
```
On Fire OS 8, use ADB to grant this permission; its settings screen does not provide it.
### Screensaver
On Android TV and Google TV, screenRIG is one of the TV's screensavers. Open **Screen saver** in the TV's **Settings** and select **screenRIG**. When the TV would start its screensaver, the Player comes to the front and plays your content. No permission is needed.
### Updating
Run the install steps again. Android installs the higher version over the installed one and keeps your pairing. Only a higher version replaces the installed one.
### Google Play
The APK and the Google Play build share package `ai.screenrig.player`. If the Google Play build is installed, uninstall it first. Pair the Player again after you install the APK.
## Linux and Raspberry Pi
The Linux Player is one self-contained package for 64-bit Linux, built for `x86_64` PCs and for `aarch64` boards such as the Raspberry Pi. Qt, Qt WebEngine and GStreamer are inside the package. The machine needs the glibc version listed for its architecture at https://screenrig.ai/linux/, a Wayland session or the `cage` kiosk compositor, and its own GPU drivers, fonts, CA certificates and audio service.
Install it with the installer, which picks the build for the machine and verifies it against `SHA256SUMS`:
```sh
curl -fsSL https://screenrig.ai/linux/install.sh | sh
```
On a dedicated screen, add `--kiosk` (`sh -s -- --kiosk`) to start the Player at boot inside `cage` under a systemd service. Run the installer again to upgrade, or with `--uninstall` to remove it. Manual install: download `screenrig-player-linux-x86_64.tar.gz` or `screenrig-player-linux-aarch64.tar.gz` and `SHA256SUMS` from https://screenrig.ai/linux/, check them with `sha256sum --ignore-missing -c SHA256SUMS`, extract to `/opt/screenrig-player`, and run `/opt/screenrig-player/screenrig-player`.
Debian 13, Raspberry Pi OS (trixie, 64-bit), Ubuntu, Fedora and Arch Linux run the Player when they meet the package's glibc requirement. Debian 12 and Raspberry Pi OS bookworm ship an older glibc; upgrade them first. Per-distribution packages for a kiosk install are in the [Linux download notes](https://screenrig.ai/downloads.md#linux).
### Raspberry Pi
Use Raspberry Pi OS (64-bit) based on trixie; the 32-bit and bookworm images cannot run the Player. Raspberry Pi 5 decodes HEVC in hardware up to 4K, so upload 4K video with `screenrig media upload --codec hevc`; H.264 suits 1080p. Raspberry Pi 4 plays 1080p. Raspberry Pi OS Lite with `--kiosk` boots straight into the Player.
### Video walls
One Linux Player drives two or three displays as one wall. A Raspberry Pi 5 drives two; an Intel mini PC such as the Quieter 4C drives two or three. The wall needs the `--kiosk` install and `wlr-randr` (`sudo apt install wlr-randr`).
`screen show` lists the screen's outputs, for example `HDMI-A-1`. Name them in physical order, left to right for a row and top to bottom for a column. `--rotation` turns every display clockwise by 0 (the default), 90, 180 or 270 degrees; 90 and 270 are portrait panels.
```sh
screenrig screen wall set SCREEN_ID --outputs HDMI-A-1,HDMI-A-2 --arrangement row [--rotation 0|90|180|270]
screenrig screen wall clear SCREEN_ID
```
After a wall change each display shows its number and output name for 20 seconds, so you can check the order.
A playlist built for the wall carries a `format` (`displays`, `arrangement` and `orientation`) and one page canvas, in 1080p design units per display. A 4K panel needs nothing different. A screen plays a wall playlist only when its wall has the same shape.
| Displays | Arrangement | Landscape canvas | Portrait canvas |
| --- | --- | --- | --- |
| 2 | row | 3840 × 1080 | 2160 × 1920 |
| 2 | column | 1920 × 2160 | 1080 × 3840 |
| 3 | row | 5760 × 1080 | 3240 × 1920 |
| 3 | column | 1920 × 3240 | 1080 × 5760 |
Place an item with `displays`: `[1,2,3]` spans the wall, `[2]` sits on one display and `[1,2]` spans two. Or give a free `rect` on the wall canvas. A card lays out inside its `displays`, so `center` on `[2]` sits in the middle of display 2; without `displays` it uses every display. On a screen with a wall, an ordinary playlist (no `format`) plays mirrored on every display.
Render wall video at the wall's aspect ratio within 4K, such as 3840 × 720 for three landscape displays in a row and 3840 × 1080 for two, and place it with `content_fit: fill`. Keep text and faces off the seams between displays.
```json
{
"name": "Lobby wall",
"format": { "displays": 3, "arrangement": "row", "orientation": "landscape" },
"pages": [
{
"id": "welcome",
"canvas": { "width": 5760, "height": 1080, "background": "#000000FF" },
"transition": { "type": "crossfade", "duration_ms": 500 },
"advance": { "mode": "media_end" },
"primitives": [
{
"id": "film",
"primitive": "video",
"selector": { "by": "id", "media_id": "med_01EXAMPLEWALL000000000" },
"displays": [1, 2, 3],
"layer": 0,
"content_fit": "fill"
},
{
"id": "menu",
"primitive": "card",
"card": "crd_01EXAMPLEMENU000000000",
"layout": "center",
"displays": [2],
"content_fit": "fill"
}
]
}
]
}
```
## Install the Player web app
1. Open [play.screenrig.ai/player/](https://play.screenrig.ai/player/) on the screen device.
2. On iOS, use Safari: **Share → Add to Home Screen**. On Android, use Chrome: **Install app** or **Add to Home Screen**.
3. Open the installed PWA and follow its displayed setup instructions.
4. Keep the PWA in the foreground on the screen device.
A Player pairs with the API of its own environment: `play.screenrig.ai` with `api.screenrig.ai`. When the CLI uses another API origin, `--api-url https://api.DOMAIN`, open `https://play.DOMAIN/player/` instead.
Your agent needs the [official plugin](https://screenrig.ai/docs/start.md) to publish content to the Player.
## ChromeOS kiosk
Managed ChromeOS devices, such as a Chromebox, a Chromebase or a ChromeOS Flex PC, run the Player web app as a kiosk app from the Google Admin console. The device boots straight into the Player, keeps it full screen, and starts it again if it closes.
1. In the Google Admin console, open **Devices → Chrome → Apps & extensions → Kiosks** and select the organizational unit for your screens.
2. Add the app by URL: your project's [fleet link](https://screenrig.ai/docs/players.md#chromeos-fleet), or `https://play.screenrig.ai/player/` with the trailing slash to pair each device by its code.
3. Set it to auto-launch, and turn on **Allow app to manage power**.
4. In the device's kiosk power settings, set the idle action to **Do nothing**, so the screen never dims or sleeps.
5. Restart the device. With a fleet link, the Player joins your project as a new screen on its own. Without one, it shows its pairing code: give the code to your agent.
In the kiosk session the Player reads the device's serial number and the asset ID and location you annotate on the device in the Admin console. They appear in the screen's host details in the dashboard and in `screen show`. When a powerwash or reinstall gives the device a new Player identity, the serial lets your agent reconnect it to its existing screen with `screen recover` instead of pairing a new one.
For the soundtrack, allow autoplay for `https://play.screenrig.ai` with the `AutoplayAllowlist` policy.
### One URL for the whole fleet
A fleet link is one Player URL that turns every device opening it into its own screen in your project, with no pairing code. Ask your agent for one (`screenrig fleet-links create`), or create it in the dashboard under **Settings → Fleet links**, and put its URL in the kiosk app in step 2. Each new device joins with the link's tags and playlist and takes its name from the asset ID, then the location, you annotate on it in the Admin console.
A device that is already a screen stays that screen through restarts and updates. After a powerwash or reinstall it comes back as the same screen, once its old Player identity has been silent for ten minutes. Cap a link with a most-screens limit, turn it off to stop new screens joining, or rotate it to replace a URL that was shared too widely. Screens a link already made keep playing through all three. Keep the URL in the Admin console: it creates screens in your project.
### Display power over RS-232
Connect the display's RS-232 control port to the ChromeOS device with a USB serial adapter, and grant the adapter to `https://play.screenrig.ai` with the `SerialAllowUsbDevicesForUrls` policy (the adapter's USB vendor and product IDs) or `SerialAllowAllPortsForUrls`. At start the Player finds a Samsung (MDC), LG, NEC or Philips (SICP) display on the granted port at the factory-default 9600 baud and display ID. It then switches the display's own power, standby and back on, and reports the power state the display reads back. The screen's host capabilities list Display power (RS-232).
## Advertising on your screens
The Player you already use is also the ad Player: there is nothing extra to
install.
Selling is a choice you make per screen, through the same official plugin and
CLI. Opt an owned screen in with `screenrig ads inventory update scr_LOBBY
--enabled` and describe it publicly with the site name, city, region, venue
type, and audience tags you choose. Define reusable ad slots with `screenrig
ads slots create` — accepted media (image or video), the longest image and
video durations, and an optional rate override for that slot. A slot definition
alone changes nothing on the glass; placing its adslot page in one of your
playlists is what gives that screen an actual ad break, and every other page
keeps playing normally.
Paid ads require a Player that supports adslot playback. The server serves a
Player without that support only the ordinary playlist, so that screen plays
house content and no paid advertising; a capable Player requests a fill for
each adslot page and skips any slot it cannot fill, keeping the playlist
moving. Buyers pair nothing — they buy from your inventory through the
invitation you send with `screenrig invitations create --kind ad-buyer --email ADDRESS --screen-id scr_LOBBY`.
[Advertising rates and serving fees](https://screenrig.ai/pricing.md#advertising)
are on the pricing page; the plugin, project, and first-screen steps are in the
[Start guide](https://screenrig.ai/docs/start.md).
## Commercial displays
Samsung Smart Signage (Tizen) runs the native screenRIG Player.
BrightSign players running OS 9.1 or newer auto-start the screenRIG Player from an SD card. Extract the package to the card root, insert it, and power on. The player applies its hardware policy and opens the screenRIG Player.
1. Set the player's clock and network first. A wrong clock stops the secure connection.
2. Extract it to the root of a FAT32 SD card and insert the card.
3. Power on the player. It starts the package and shows the pairing code.
4. Give the code to your agent.
Other commercial displays with a built-in HTML5 browser or URL launcher can open [play.screenrig.ai/player/](https://play.screenrig.ai/player/) directly and follow the web app steps above. The display must keep the page in the foreground and allow it to store data. Android TV and streaming boxes with a full web browser can do the same: open play.screenrig.ai/player/ in the box’s browser, give your agent the pairing code, and keep the page in the foreground.
## Streams and fallback images
Use stream for a live feed and video for an uploaded file. A stream needs a ready uploaded image from the same account as its fallback. The image appears while connecting, if playback stalls, or when the Player cannot receive the source.
### Prepare a feed
Use a public HTTPS HLS playlist without embedded credentials, or a camera's RTSP URL. For the Web Player, the playlist, segments, and keys must allow cross-origin requests from the Player origin. H.264 video with AAC audio is a practical starting profile; decoding depends on the device. Audio is muted by default, and browser autoplay rules still apply.
### Choose timing and transport
Use at most one stream per page and duration-based advance. Supply one or two sources with different protocols, in preference order. A source can give only its `url`: an `https` URL is HLS, an `rtsp` or `rtsps` URL is RTSP. For multicast, use an administratively scoped IPv4 group in 239/8 and a UDP port; add an HLS alternative for other Players. screenRIG does not convert multicast into HLS. Streams are not cached for offline replay; the fallback image is.
### Play a camera directly
Android, Amazon and Linux Players open an `rtsp://` or `rtsps://` source themselves, from the Player's own network, with no relay. Use the URL the camera or recorder gives, including a `user:pass@` login. For a UniFi Protect camera, turn on RTSP for a channel in the camera's Protect settings and copy its URL; the Player needs a route to the Protect console. Other Players play the HLS alternative or show the fallback image.
### Enable multicast reception
On Android, open the operator menu, choose **Settings** and enable Multicast streams; it is off by default. On Qt, enable SCREENRIG_ENABLE_MULTICAST=1 in the Player launch environment and check --capabilities-json. The network must carry the selected multicast group and port. This version does not provide DRM, RTP, custom authentication headers, or stream transcoding.
## Soundtracks
A playlist soundtrack plays on every Player. The Player downloads and verifies each MP3 track with the rest of the playlist, then plays the tracks in order while pages change. Page transitions never stop or restart the music, and the soundtrack keeps playing offline from the cached tracks. A cued soundtrack (`cued: true`) plays a track only when a page cue starts it and is silent after that track ends until the next cue. A page whose `advance` is `audio_end` ends when its cued track ends; if the Player cannot play the track, the page lasts the track's length.
When the agent republishes the playlist, the current track keeps playing if it is still in the new soundtrack. The soundtrack volume is multiplied by the Player volume, so the operator volume setting or the display's own volume control still decides how loud the screen is.
Browsers can block sound until someone touches the page. The Player web app keeps showing pages and starts the soundtrack on the first tap or key press. For an unattended kiosk browser, allow autoplay with sound; in Chromium, launch with `--autoplay-policy=no-user-gesture-required`; on a [ChromeOS kiosk](https://screenrig.ai/docs/players.md#chromeos), set the `AutoplayAllowlist` policy. Native Players need no setting.
## Device health and display control
Every Player reports device health every fifteen minutes, and at once when its display connection or power changes. It declares the device controls it supports: remote reboot, and the display power methods it can use. What a Player can read and switch depends on the platform and on how the device is set up.
Each screen's actual capabilities appear in `screen show` as its host capabilities, next to its latest health report, so the agent knows before it acts whether that screen can reboot or switch its display. The table shows what each Player can do.
| Player | Health reported | Display power | Reboot |
| --- | --- | --- | --- |
| Web / PWA | Player uptime, CPU cores, display state, and network type where the browser exposes it | RS-232 on a ChromeOS kiosk with a granted serial port; on-screen blackout | No |
| Android (Google Play) | Device and Player uptime, memory, CPU cores, display connection and power, network and Wi-Fi signal, crashes, and renderer restarts | On-screen blackout | No |
| Android (managed, device owner) | As Google Play, plus CPU temperature | Backlight; HDMI-CEC on a privileged install; on-screen blackout | Yes |
| Amazon Signage Stick | As Google Play | On-screen blackout | No |
| Linux and Raspberry Pi | Device and Player uptime, memory, CPU load, temperature, display connection and power, network and Wi-Fi signal, and crashes | HDMI-CEC with a CEC device and `cec-ctl`; DDC/CI where `ddcutil` finds the monitor; panel backlight; on-screen blackout | Yes, after a `--kiosk` install |
| macOS | Device and Player uptime, memory, CPU load and cores, display connection and power, and network type | Display sleep, once it has worked on that Mac; on-screen blackout | No |
| Apple TV | Device and Player uptime, memory, CPU load and cores, display power, and network type | On-screen blackout | No |
| Windows | Device and Player uptime, memory, CPU cores, display connection and power, network type, and renderer restarts | DDC/CI where the monitor answers; monitor off; on-screen blackout | Yes, when the account may shut down the PC |
| BrightSign | The web Player readings | HDMI-CEC through the BrightSign shell; on-screen blackout | Yes, through the BrightSign shell |
## Control a screen on the device
Once the screen is paired, press OK on the remote to open its operator menu. The first screen of the menu holds:
- **Screen name.** Select it to rename the screen.
- **Playlist.** Its hint is the playlist the screen plays. Select it, or press Right, to list every playlist in the project in alphabetical order, and choose one to switch the screen to it. A takeover or playlist schedule still decides what plays; the hint always names what is playing.
- **Page.** Its hint is the name of the page now showing; a page's name is its identifier. The menu opens on this row. Press Left or Right to step to the previous or next page, or select it to list the playlist's pages in playback order and choose one to jump to. The chosen page starts from its beginning.
- **Settings.** Brightness, volume and reset, and on Android multicast reception and start on boot.
- **Exit settings** closes the menu from any screen.
Back, or Left on a list, returns to the previous screen. The menu closes by itself after 60 seconds without input.
### Pause and resume
Press Play/Pause on the remote (K on Windows) to pause the screen; the Paused chip shows. A paused screen holds its page timer, the page's video and the soundtrack. Press the button again and everything continues from where it stopped: a page set to show for 20 seconds, paused at 10 seconds, shows for the remaining 10 seconds, and the music resumes from the same point instead of starting over. Moving to the next or previous page, or choosing one in the menu, keeps the pause: the new page waits at its start until you resume. Cards, web pages and live streams keep running while paused. A pause ends by itself after 60 minutes.
## Check your first screen
Give your agent the intended screen and ask it to publish a simple welcome message. Ask for a screenshot when the Player is showing it.
If the screen is absent from the agent's list, confirm that the Player is open and its setup is complete. If content does not update, check the device's connection and ask the agent to inspect screen state and playback evidence.
Once the screen is paired, its [operator menu](#operator-menu) names the screen and shows its playlist and page.
[Continue with the agent workflow](https://screenrig.ai/docs/agents.md).