Obscreen Docs

Appearance

Raspberry Pi ​

The DIY digital signage player. Compact, silent and energy-efficient: drives any HDMI screen.

About this platform ​

The Raspberry Pi is the reference micro-computer for digital signage. With Obscreen, you have two install paths:

  • Additive install: add the Obscreen player on top of your existing Raspberry Pi OS for a quick setup.
  • Obscreen OS: flash a dedicated, fully managed image so the Pi boots directly into your content with zero configuration.

Technical specifications ​

BoardRaspberry Pi 3B+ / 4 / 5
ArchitectureARM64
RAM1 GB minimum (2 GB recommended)
StoragemicroSD 8 GB+
ResolutionUp to 4K (Pi 4/5)
OSRaspberry Pi OS or Obscreen OS

Hardware ​

First, grab a Raspberry Pi. Version 4 or later is ideal, but it should run fine on any version with enough RAM, as the browser can be a bit heavy.

Power supply

Make sure you have a power supply with at least 2A of current to avoid any issue.

You'll need an SD card with at least 8GB of storage. Then download Raspberry Pi Imager.

Option 1: Additive install (on top of Raspberry Pi OS) ​

Add the Obscreen player to your existing Raspberry Pi OS. The player runs alongside your existing system.

When you start the Imager, choose Raspberry Pi OS Lite under category Raspberry PI OS (other).

Recommendation

Use the Lite version of Raspberry Pi OS for better performance. It works with the Desktop version but it's not recommended.

Software Installation ​

Log into your Raspberry Pi locally or via SSH (by default it's ssh pi@raspberrypi.local).

Install player autorun by executing following script (will install chromium, x11, pulseaudio and obscreen-player systemd service)

bash
curl -fsSL https://raw.githubusercontent.com/obscreen/obscreen/master/system/client/install-browser-player.sh -o /tmp/install-browser-player.sh && chmod +x /tmp/install-browser-player.sh && sudo /bin/bash /tmp/install-browser-player.sh $USER $HOME

INFO

3rd variable $STUDIO_URL after $HOME is used to automate the configuration of studio endpoint.

4th variable $PLAYER_BROWSER after $STUDIO_URL is used to set the browser to use for the player. Available values are:

  • chromium
  • firefox

You can use --disable-interactive (at the end of the line) to make the script non-interactive.

If previous script successfully finished, then restart your device by executing sudo reboot

How to Restart ​

Use systemctl: sudo systemctl restart obscreen-player.service

Sound Activation ​

WARNING

First reboot your device after the player installation with sudo reboot (or by unplugging and replugging the device).

Set the audio channel to HDMI: sudo raspi-config nonint do_audio 1 (0 is for the 3.5mm jack output).

If you have more than one audio device, you can precisely select which one to use by executing sudo raspi-config and following these steps:

  • Select 1 System Options
  • Select S2 Audio
  • Select your audio output
  • Select Ok
  • Select Finish

Screen Configuration ​

Screen configuration is set in file [obscreen-player-dir]/var/run/play under these variables:

SCREEN_RESOLUTION ​

You can change it by editing the file and fill it with a supported resolution To get the list of supported resolutions:

  1. Run: DISPLAY=:0 xrandr
  2. Replace SCREEN_RESOLUTION=auto with your preferred resolution (see an example below).
bash
SCREEN_RESOLUTION=1920x1080

SCREEN_ROTATE ​

Possible values are:

  • For 0° set: normal
  • For 90° set: left
  • For 180° set: right
  • For 270° set: inverted

Pointing and Interaction Configuration ​

Pointing and interaction configuration is set in file [obscreen-player-dir]/var/run/play under these variables:

Mouse cursor options ​

MOUSE_CURSOR_HIDDEN ​

Set to true to hide the mouse cursor on the screen.

MOUSE_CURSOR_HIDDEN=true

Touchscreen gestures options ​

TOUCH_ENABLED ​

Set to true to enable touchscreen gesture support. Default: true

TOUCH_ENABLED=true

TOUCH_PINCH_DISABLED ​

Set to true to disable pinch gesture detection (to prevent zooming with two fingers). Default: false

TOUCH_PINCH_DISABLED=true

TOUCH_VIRTUAL_KEYBOARD ​

Set to true to enable virtual keyboard support. Default: false

TOUCH_VIRTUAL_KEYBOARD=false

Host Identification Configuration ​

To help you identify and locate your device, you can set the following metadata in [obscreen-player-dir]/var/run/play file:

Name & Icon ​

bash
CLIENT_HOSTNAME="My Device"
CLIENT_ICON=auto # any font-awesome icon name (i.e. fa-desktop, fa-laptop, fa-tablet, fa-mobile, fa-tablet-alt, fa-mobile-alt)

Search for icons

You can browse the free icon catalog here.

Positioning ​

Choose one of the following options from more precise to less precise location:

1. Precise positioning ​

bash
CLIENT_LONGITUDE=
CLIENT_LATITUDE=

2. Structured address-based positioning ​

bash
CLIENT_STREET=
CLIENT_CITY=
CLIENT_STATE=
CLIENT_COUNTRY=
CLIENT_POSTAL_CODE=

3. Query address-based positioning ​

bash
CLIENT_ADDRESS_QUERY= # (e.g. "1600 Pennsylvania Avenue NW, Washington, DC 20500")

See more about customizing the player's URL here.

Playlist Configuration ​

Playlist URL is set in file var/run/play under variable STUDIO_URL. You can change it by editing the file and fill it with either:

Playlist URL

To connect the player to a specific playlist using its ID
http://<STUDIO_URL>/use/<playlist_id>

Playgroup URL

To connect the player to a specific playgroup using its ID
http://<STUDIO_URL>/group/<playgroup_id>

Option 2: Obscreen OS (dedicated image) ​

Flash a ready-made image so the Pi becomes a locked-down, maintenance-free signage player.

  1. Download the Obscreen OS ARM image from obscreen.io.
  2. Flash it to your microSD card with Balena Etcher or Raspberry Pi Imager.
  3. Insert the SD card and boot the Pi. The device appears in your Obscreen dashboard automatically.
  4. Assign a playlist from your dashboard: content starts playing immediately.

What you get ​

  • Locked-down OS: no desktop, no browser, no package manager. Only the player runs.
  • OTA updates: automatic updates keep your screens on the latest version.
  • Watchdog recovery: built-in auto-recovery in case of failure.

TIP

Both install methods support OTA updates. Obscreen OS is recommended for fleets of unattended signage screens; the additive install is better when you want to keep using the Pi for other tasks.