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 for better performance! It may work with Desktop version, but it's not recommended.

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-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 ​

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:

  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>