Image depuis un script

Un script Python qui dessine un graphique, remplace par celui-ci l’image précédente d’une playlist et publie. Cron le lance toutes les cinq minutes. Les blocs de cette page forment un seul fichier.

1 Obtenez un token

Ouvrez le CMS dans Paramètres, Applications connectées et cliquez sur Générer un token. Un membre sans droits d’administrateur ne voit pas cet onglet.

Choisissez ensuite l’organisation, qui détermine les écrans que le programme voit, et cliquez sur Autoriser. La page suivante affiche l’identifiant client et le token de rafraîchissement, une seule fois. Copiez les deux.

Dans votre terminal, définissez l’identifiant client et le chemin du fichier de token, puis écrivez le token de rafraîchissement dans ce fichier. read -rs attend sans rien afficher : collez le token de rafraîchissement et appuyez sur Entrée, il reste ainsi hors de l’historique du shell :

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"

Installez les deux dépendances dans un venv, car le Python de Homebrew et Debian 12 ou plus récent refusent un pip install en dehors :

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

Placez les blocs ci-dessous dans l’ordre dans gibeon.py et lancez python3 gibeon.py.

2 Choisissez la playlist et l’écran

Le script a besoin de deux id. L’id de la playlist figure dans la barre d’adresse du CMS quand vous ouvrez une playlist : /playlists/PLAYLIST_ID/content. L’id de l’écran y figure quand vous ouvrez un écran : /devices/PLAYER_ID.

export GIBEON_PLAYLIST_ID=PLAYLIST_ID
export GIBEON_PLAYER_ID=PLAYER_ID

La playlist doit déjà être sur l’écran : ce script ne l’assigne pas. Faites-le une fois avec la dernière étape du démarrage rapide Python, Node.js ou Go, dont le lien figure en bas de cette page.

La playlist appartient à ce script seul : chaque exécution supprime tous les éléments plus anciens, quels qu’ils soient. Utilisez donc une playlist distincte. Ne mettez la playlist que sur cet écran : le script ne publie que cet écran, et un autre écran avec la même playlist garderait une image que le script supprime ensuite.

3 Rafraîchissez le token

Un token d’accès est valable 60 minutes. Chaque rafraîchissement renvoie aussi un nouveau token de rafraîchissement : une valeur dans l’environnement est donc périmée après une exécution.

Le programme écrit le nouveau token dans un fichier temporaire du même répertoire, applique chmod 600 et le renomme par-dessus le fichier de GIBEON_REFRESH_TOKEN_FILE. Il n’utilise le token d’accès qu’ensuite. Un processus qui s’arrête pendant cette utilisation conserve ainsi un token de rafraîchissement valide.

Chaque requête vérifie le statut : en cas d’erreur, raise_for_status arrête le programme avec un code de sortie non nul.

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 Vérifiez l’écran et lisez la playlist

Le script lit les deux id, récupère l’écran et lit les éléments de la playlist, avant de créer un asset. Si un id est périmé, il s’arrête ici et aucune image n’est ajoutée.

# 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 Dessinez le graphique

Ce bloc dessine des chiffres d’exemple fixes en 1920 sur 1080 pixels. Remplacez-les par les vôtres. Figure n’a pas besoin d’un écran : cela fonctionne donc aussi sous cron. Un écran affiche l’image à la taille du téléversement : dessinez-la donc à la taille de l’écran, comme ce script en 1920 sur 1080.

Tout PNG convient, y compris celui du 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 Téléversez l’image

Un téléversement se fait en deux étapes. POST /v1/assets crée l’asset, puis le PUT envoie les octets avec Content-Type: image/png. Le file_size ne peut s’écarter des octets envoyés que de 10 % au maximum.

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 Remplacez l’élément dans la playlist

Le script utilise les éléments lus à l’étape de contrôle : cette liste ne contient donc que des éléments plus anciens. Il ajoute le nouvel élément, puis supprime les anciens. Ainsi, la playlist n’est jamais vide.

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 Publiez

Tant que vous ne publiez pas, l’écran affiche l’image précédente. La publication construit un nouveau snapshot et prévient l’écran immédiatement.

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

9 Supprimez les images plus anciennes

Le script ne supprime que les assets des éléments qu’il vient de retirer. Il le fait après la publication, car le snapshot précédent les utilisait encore. L’API répond 409 tant qu’un autre élément utilise un asset : le script l’accepte et laisse cet asset en place. Toute autre erreur l’arrête. Pour finir, il affiche l’id du nouvel 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 Lancez-le toutes les cinq minutes

Cron ne lit pas votre terminal : les variables vont donc dans la crontab. Remplacez /PATH/TO/PROJECT par le répertoire qui contient gibeon.py, .venv et le fichier de token :

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 saute une exécution tant que la précédente est en cours : deux exécutions ne peuvent donc pas se disputer le fichier de token. Le verrou est un fichier distinct, car le script renomme le fichier de token.

Un token d’accès expire après 60 minutes. Chaque exécution rafraîchit d’abord le token et conserve le nouveau token de rafraîchissement : le script continue donc de tourner au-delà de ces 60 minutes.

La sortie et les erreurs de chaque exécution vont dans gibeon.log.

Et ensuite