Obscreen Docs

Appearance

Raspberry Pi ​

Hardware ​

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

Info

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 RaspberryPi Imager When you start the Imager, choose Raspberry Pi OS Lite under category Raspberry PI OS (other).

Warning! 🚨

Download Lite version of Raspberry Pi OS only! If your OS boots with a desktop environment, you WILL NOT be able to use it as a player.

Software Installation ​

Log into your RaspberryPi locally or via ssh (by default it's ssh [email protected])

How to Install ​

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-client-player.sh -o /tmp/install-client-player.sh && chmod +x /tmp/install-client-player.sh && sudo /bin/bash /tmp/install-client-player.sh $USER $HOME

INFO

You can set a third variable $STUDIO_URL after $HOME to automate the configuration of studio endpoint. 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 ​

Just use systemctl by executing sudo systemctl restart obscreen-player.service

Sound Activation ​

WARNING

First you have to reboot your device if you never did after obscreen player installation with command sudo reboot or by unplugging and plugging the device again.

You have to set audio channel to HDMI sudo raspi-config nonint do_audio 1 (0 is for jack 3.5 output)

If you have more than one audio device, you can precisely select which one to use by executing sudo raspi-config and follow 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 just run: DISPLAY=:0 xrandr Then replace SCREEN_RESOLUTION=auto with your preferred resolution. (e.g. SCREEN_RESOLUTION=1920x1080)

SCREEN_ROTATE ​

Possible values are:

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

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)

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")

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>