Image from a script

A Python script that draws a chart, replaces the previous image in a playlist with it and publishes. Cron runs it every five minutes. The blocks on this page form one file.

1 Get a token

Open the CMS at Settings, Connected apps and click Generate token. A member without admin rights does not see this tab.

Then choose the organization, which decides the screens the program sees, and click Allow. The next page shows the client ID and the refresh token, once. Copy both.

In your terminal, set the client ID and the path of the token file, then write the refresh token to that file. read -rs waits without showing anything: paste the refresh token and press Enter, so it stays out of the shell history:

export GIBEON_CLIENT_ID=CLIENT_ID
export GIBEON_REFRESH_TOKEN_FILE=./gibeon-refresh-token
touch "$GIBEON_REFRESH_TOKEN_FILE"
chmod 600 "$GIBEON_REFRESH_TOKEN_FILE"
read -rs GIBEON_REFRESH_TOKEN && printf '%s' "$GIBEON_REFRESH_TOKEN" > "$GIBEON_REFRESH_TOKEN_FILE"

Install the two dependencies in a venv, because Homebrew Python and Debian 12 or newer refuse a pip install outside one:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install requests matplotlib

Put the blocks below in order in gibeon.py and run python3 gibeon.py.

2 Choose the playlist and the screen

The script needs two ids. The playlist id is in the CMS address bar when you open a playlist: /playlists/PLAYLIST_ID/content. The screen id is there when you open a screen: /devices/PLAYER_ID.

export GIBEON_PLAYLIST_ID=PLAYLIST_ID
export GIBEON_PLAYER_ID=PLAYER_ID

The playlist must already be on the screen: this script does not assign it. You do that once with the last step of the Python, Node.js or Go quickstart, linked at the end of this page.

The playlist belongs to this script alone: every run removes every older item, whatever it is. So use a separate playlist. Put the playlist on this one screen only: the script publishes only that screen, and another screen with the same playlist would keep an image the script then deletes.

3 Refresh the token

An access token lasts 60 minutes. Every refresh also returns a new refresh token, so a value in the environment is stale after one run.

The program writes the new token to a temp file in the same directory, sets chmod 600 and renames it over the file in GIBEON_REFRESH_TOKEN_FILE. Only then does it use the access token. A process that dies while using it keeps a working refresh token.

Every request checks the status: on an error, raise_for_status stops the program with a non-zero exit code.

import os
import tempfile

import requests

token_file = os.environ["GIBEON_REFRESH_TOKEN_FILE"]

with open(token_file) as f:
    refresh_token = f.read().strip()

response = requests.post(
    "https://id.gibeon.io/auth/v1/oauth/token",
    data={
        "grant_type": "refresh_token",
        "client_id": os.environ["GIBEON_CLIENT_ID"],
        "refresh_token": refresh_token,
    },
    timeout=30,
)
response.raise_for_status()
tokens = response.json()

# Store the new refresh token before anything uses the access token.
fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(token_file) or ".")
with os.fdopen(fd, "w") as f:
    f.write(tokens["refresh_token"])
os.chmod(tmp_path, 0o600)
os.replace(tmp_path, token_file)

headers = {"Authorization": f"Bearer {tokens['access_token']}"}

4 Check the screen and read the playlist

The script reads the two ids, fetches the screen and reads the playlist’s items, all before it creates an asset. If an id is stale, it stops here and no image is added.

# Both are required: a missing one stops the run before it changes anything.
playlist_id = os.environ["GIBEON_PLAYLIST_ID"]
player_id = os.environ["GIBEON_PLAYER_ID"]

# A stale screen id stops the run here, before an asset exists.
response = requests.get(
    f"https://www.gibeon.io/v1/players/{player_id}",
    headers=headers,
    timeout=30,
)
response.raise_for_status()

# Read before adding, so this list holds only the older items.
response = requests.get(
    f"https://www.gibeon.io/v1/playlists/{playlist_id}/items",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
older_items = response.json()["data"]

5 Draw the chart

This block draws fixed sample numbers at 1920 by 1080 pixels. Replace them with your own. Figure needs no display, so this also works under cron. A screen shows the image at the size you upload, so draw it at screen size, as this script does at 1920 by 1080.

Any PNG works, also the one from the Grafana image renderer.

from datetime import datetime

from matplotlib.figure import Figure

figure = Figure(figsize=(16, 9), dpi=120)
axes = figure.subplots()
axes.bar(["North", "East", "South", "West"], [12, 19, 7, 15])
axes.set_title(datetime.now().strftime("Updated at %H:%M"))
figure.savefig("chart.png")

6 Upload the image

An upload has two steps. POST /v1/assets creates the asset, then the PUT sends the bytes with Content-Type: image/png. The file_size may differ from the bytes you send by at most 10 percent.

with open("chart.png", "rb") as f:
    png = f.read()

response = requests.post(
    "https://www.gibeon.io/v1/assets",
    headers=headers,
    json={
        "name": "chart.png",
        "asset_type": "image",
        "mime_type": "image/png",
        "file_size": len(png),
    },
    timeout=30,
)
response.raise_for_status()
asset_id = response.json()["data"]["id"]

response = requests.put(
    f"https://www.gibeon.io/v1/assets/{asset_id}/upload",
    headers={**headers, "Content-Type": "image/png"},
    data=png,
    timeout=60,
)
response.raise_for_status()

7 Replace the item in the playlist

The script uses the items it read in the check step, so that list holds only older items. It adds the new item and then deletes the older ones. That way the playlist is never empty.

response = requests.post(
    f"https://www.gibeon.io/v1/playlists/{playlist_id}/items",
    headers=headers,
    json={"type": "image", "asset_id": asset_id, "duration_seconds": 30},
    timeout=30,
)
response.raise_for_status()

for item in older_items:
    item_id = item["id"]
    response = requests.delete(
        f"https://www.gibeon.io/v1/playlists/{playlist_id}/items/{item_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()

8 Publish

Until you publish, the screen shows the previous image. Publishing builds a new snapshot and tells the screen right away.

response = requests.post(
    f"https://www.gibeon.io/v1/players/{player_id}/publish",
    headers=headers,
    timeout=30,
)
response.raise_for_status()

9 Remove the older images

The script deletes only the assets of the items it just removed. It does so after the publish, because the previous snapshot still used them. The API answers 409 while another item uses an asset: the script accepts that and leaves the asset alone. Any other error stops it. Last, it prints the id of the new asset.

# A YouTube item has no asset_id, and two items can share an asset.
older_asset_ids = {item["asset_id"] for item in older_items if item["asset_id"]}

for older_asset_id in older_asset_ids:
    response = requests.delete(
        f"https://www.gibeon.io/v1/assets/{older_asset_id}",
        headers=headers,
        timeout=30,
    )
    # A 409 means another item still uses the asset, so it stays.
    if response.status_code != 409:
        response.raise_for_status()

print(asset_id)

10 Run it every five minutes

Cron does not read your terminal, so the variables go in the crontab. Replace /PATH/TO/PROJECT with the directory that holds gibeon.py, .venv and the token file:

GIBEON_CLIENT_ID=CLIENT_ID
GIBEON_REFRESH_TOKEN_FILE=./gibeon-refresh-token
GIBEON_PLAYLIST_ID=PLAYLIST_ID
GIBEON_PLAYER_ID=PLAYER_ID
*/5 * * * * cd /PATH/TO/PROJECT && flock -n gibeon.lock .venv/bin/python gibeon.py >> gibeon.log 2>&1

flock -n skips a run while the previous one is busy, so two runs cannot race on the token file. The lock is a separate file, because the script renames the token file.

An access token expires after 60 minutes. Every run refreshes first and stores the new refresh token, so the script keeps running past those 60 minutes.

The output and the errors of every run go to gibeon.log.

What’s next