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.