screenRIG
Se connecterCommencer

Cartes intégrées

Ajouter des composants en direct à une liste de lecture : menus, horloges, files d’attente, scores, météo et jauges. Choisissez une carte, définissez ses propriétés et publiez.

Une carte est un composant intégré sur un canevas de liste de lecture. Elle remplit son rectangle avec une horloge, un menu, une file d’attente ou un autre détail en direct, et peut se placer sur des images ou vidéos.

Mises en page et ancres

Définissez layout et anchor dans l’élément de la liste de lecture, à côté de card. layout est requis.

layoutBoîte en unités de conception 1080panchor
fullToute la toile, paysage ou portraitaucun
freeVotre propre rect et layeraucun
center900 × 420, centréaucun
wideLe canevas est encastré de 80 en haut et en bas et de 30 sur les côtésaucun
headerTout le bord supérieur par 80aucun
footerTout le bord inférieur par 80aucun
corner270 × 270, aligné au cointop-left, top-right, bottom-left, bottom-right
chip240 × 70, encastré à 30 des deux bords les plus prochestop-left, top-right, bottom-left, bottom-right
stripTout le bord par 120top, bottom, left, right

Les tailles s’adaptent par min(canvas width, canvas height) / 1080. Un canevas 4K (3840 × 2160) affiche la même taille apparente que le 1080p, et un canevas portrait la même que le paysage. Le design d’une carte suit la forme de sa boîte : bande, paysage, carré, portrait ou tour.

anchor est requis pour corner, chip et strip, et non autorisé pour full, free, center, wide, header et footer. Omettez rect et layer pour chaque mise en page sauf free : screenRIG les déduit du canevas de la page lors de l’enregistrement de la liste de lecture. Un élément free nécessite son propre rect et layer.

Composer une page avec une carte full, center ou wide, plus des cartes corner, chip et strip selon les besoins. Une page contient au maximum une carte full, center ou wide, au maximum une carte corner ou chip par coin, et au maximum une strip par bord, plus une carte avec présence qui partage ce bord. Une header et une footer sont des barres pleine largeur, 80 de haut, le long des bords supérieur et inférieur, et une page contient une barre par bord : une header prend la place strip du bord supérieur et une footer celle du bord inférieur, de sorte que ce bord ne contient aucune strip normale, tandis qu’une carte avec présence peut encore la partager. Une page peut contenir à la fois une header et une footer. Les images, vidéos et éléments web ne sont pas limités par ces règles, et un nombre quelconque de cartes free peut partager une page. Une corner ou chip sur un bord qui contient une strip se déplace vers l’intérieur de 120, et au-delà d’une header ou footer de 80 (la plus grande quand un bord contient les deux), de sorte qu’elles ne se chevauchent jamais. Une carte center, wide, header ou footer ignore les bandes.

Une strip gauche ou droite est la bande sur ce bord, large de 120 et aussi haute que le canevas. La carte se dessine comme une bande horizontale et le Player la tourne de 90 degrés autour du centre de la bande : la bande gauche dans le sens antihoraire, donc le texte se lit de bas en haut, et la bande droite dans le sens horaire, donc le texte se lit de haut en bas.

Un niveau de carte décide ses mises en page. Une carte core prend les neuf, limitées aux mises en page qu’elle dessine : seules les cartes header et footer prennent ces deux-là. Une carte fullscreen est faite pour un écran paysage ou portrait complet et prend full seulement. Un stinger est un bumper de transition de page et ne prend aucune mise en page. GET /api/card-types et screenrig cards show ID listent le niveau et les mises en page de chaque carte.

Présence

Certaines cartes ne sont présentes que tant que leur condition est vraie, comme une barre d’alertes au bord inférieur ou une puce « éclair à proximité ». En leur absence, une carte ne dessine rien. Une bande de présence sur le même bord qu’une bande normale la remplace lorsqu’elle est présente, et la bande normale revient ensuite. Une carte avec présence apparaît et disparaît avec un mouvement qui correspond à sa disposition : les bandes glissent depuis leur bord, les coins et puces montent et s’estompent, et les cartes center, wide, header, footer, full et free s’estompent.

Erreurs de mise en page

L’enregistrement d’une liste de lecture est refusé avec card_layout_invalid (400) pour une mise en page manquante ou inconnue, une ancre manquante, inconnue ou non désirée, une mise en page que le niveau ou les vues de la carte ne prennent pas, ou un rect ou layer qui n’est pas celui dérivé. Il est refusé avec card_layout_conflict (400) lorsque deux cartes revendiquent la même place sur une page. errors[0].field nomme le membre.

Thèmes

Définir params.theme sur neomustard (NeoMustard), cyanotype (Cyanotype), propaganda (Propaganda), signal (Signal), avant-garde (Avant Garde), bloom (Bloom), clear-dark (Clear Dark), clear-light (Clear Light) ou primetime (Primetime). Les cartes sur screenrig.ai s’ouvrent en Bloom et le contrôle du thème les change. Primetime est le thème animé, background none donne un arrière-plan transparent, et les dispositions d’angle et de puce utilisent la plaque compacte du thème.

Cartes cœur, plein écran et stinger

Chaque carte est de type principale, plein écran ou stinger. Les cartes principales s’adaptent à toutes les dispositions et figurent sur la page Applications. Les cartes plein écran occupent tout l’espace d’un écran en mode paysage ou portrait et possèdent leurs propres pages listées dans la référence des cartes ci-dessous. Le stinger s’affiche entre deux pages lors d’une transition.

Propriétés communes

Ces propriétés contrôlent le thème et la position de chaque carte. Définissez-les dans params.

NomTypePar défautValeurs et limitesDescription
themestring"neomustard""neomustard", "cyanotype", "propaganda", "signal", "avant-garde", "bloom", "clear-dark", "clear-light", "primetime"
backgroundstring"theme""theme", "none"aucun ne peint pas d’arrière-plan, pour superposer sur la vidéo.
accentchaîne, nulnullmotif : "^#[0-9A-Fa-f]{6}$"Remplace l’accent du thème.
layoutstring"full", "free", "center", "wide", "corner", "chip", "strip"Où la carte est placée (CONTRACT.md « Mises en page ») : full est tout l’écran, free tout rectangle donné par l’hôte, center 900x420, wide est l’écran avec marges de 80 en haut et bas et 30 sur les côtés, corner 270x270 collé à un coin, chip 240x70 à 30 du coin, strip 120 de haut le long d’un bord (tailles en pixels de design 1080p). Sans cela, une carte prend full si son rectangle remplit l’écran, sinon free.
anchorstring"top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"Dans quel coin (corner et chip) ou bord (strip) une mise en page se trouve. Corner par défaut en haut à droite et strip en bas ; les autres mises en page n’en prennent pas.

Propriétés statiques et dynamiques

Une carte est une instance dans votre projet : un identifiant crd_ qui contient les propriétés statiques de la carte et son document de données en direct. Créez-la une fois, placez son identifiant dans un élément de page, et modifiez ses valeurs quand vous le voulez.

Les propriétés statiques sont les params de l’instance : thème, emplacement, titres et similaires. Modifiez-les avec card params, puis renvoyez la liste de lecture pour qu’elle les prenne en compte. Les propriétés dynamiques sont les valeurs marquées dynamic: true dans le contrat de carte, telles que sections de menu, entrées de file d’attente ou lectures de jauge. Elles résident dans le document de données de la carte, que card data put remplace sans republier la liste de lecture.

Les Players appliquent d’abord les valeurs par défaut, puis les paramètres statiques, puis les propriétés dynamiques du document. Le document en direct ne peut pas changer le style, et params ne contient jamais de propriétés dynamiques. Une carte dont les propriétés dynamiques requises n’ont pas encore de document reste masquée jusqu’à ce qu’un document soit écrit.

Une carte, un document

Chaque carte a son propre document de données, et chaque élément de page qui contient son identifiant crd_ affiche ce document. Deux cartes Workplace Posts qui affichent des publications différentes sont deux cartes avec chacune son identifiant : une écriture dans l’une ne met à jour que les éléments qui contiennent son identifiant. Placez un même identifiant dans plusieurs éléments, sur une page ou sur plusieurs, quand ils doivent afficher le même document.

Flux

Les flux sont des données tierces récupérées et mises en cache par le backend, puis transmises à la carte par le lecteur. Pour la météo, définissez location avec un nom, une latitude et une longitude. Le backend déduit la clé de flux à partir de ces propriétés statiques ; ne pas envoyer de champ feed dans l’élément canvas. Les documents de flux portent l’attribution de la source et les horodatages de récupération. Chaque référence de carte nomme son schéma de flux et l’attribution de la source.

Affichez l’attribution d’un flux partout où ses données s’affichent : les cartes le font pour vous. Un agent lit le document que lit une carte avec GET /api/feeds/FAMILY, où la famille est le premier nom après Famille et carte dans chaque section ci-dessous. Une première lecture d’un nouveau lieu répond 202 avec Retry-After: 60 pendant que screenRIG le récupère, et toutes les cartes d’un même lieu partagent un seul document.

Marées

Les prévisions de marée pour une station, de NOAA CO-OPS : des données du domaine public pour les États-Unis et leurs territoires.

  • Famille et carte : tides et tides
  • À définir : station, l’ID de station de NOAA à sept caractères, ou location, qui choisit la station de prévision la plus proche dans un rayon de 100 km. Un lieu sans station aussi proche ne donne aucune clé de flux : la carte attend et l’API répond 400 invalid_request.
  • Données : les pleines et basses mers de deux jours avant à trois jours après, plus une série aux 15 minutes pour les stations que NOAA prévoit par harmoniques. Les hauteurs sont en mètres au-dessus du MLLW et les heures en UTC. Actualisé toutes les 6 heures.
  • Mention : Tide predictions from NOAA CO-OPS, reformatted by screenRIG; not an official NOAA product.

Lancements de fusées

Les prochains lancements de fusées dans le monde, de Launch Library 2 de The Space Devs.

  • Famille et carte : launches et launch-tracker
  • À définir : rien. Toutes les cartes affichent la même liste.
  • Données : les 20 prochains lancements avec fournisseur, lanceur, pas de tir et orbite, actualisés toutes les 15 minutes. Un lancement reste listé 24 heures après le décollage, ce qui permet à une carte d’en montrer le résultat, et le lancement sur le pas de tir reçoit aussi son déroulé de mission d’au plus 20 événements.
  • Mention : Data: The Space Devs / Launch Library 2.

Rappels de médicaments et d’aliments

Les rappels d’un organisme de santé ou d’alimentation d’un pays.

  • Famille et carte : drugalerts et drug-alerts
  • À définir : country (us, ca ou gb) et category (drug, par défaut, ou food).
  • Données : les 90 derniers jours, classe I d’abord puis du plus récent au plus ancien dans une classe, jusqu’à 100. États-Unis : les rapports d’exécution de la FDA via openFDA, datés de leur date de rapport, sans les rappels terminés ou clos. Canada : les rappels et alertes de sécurité de Santé Canada et de l’ACIA. Grande-Bretagne : les rappels de médicaments de la MHRA (classes 1 à 3) et les alertes alimentaires de la Food Standards Agency. Actualisé toutes les 3 à 6 heures.
  • Mention : celle de chaque organisme, selon sa licence ouverte : openFDA (CC0), la Licence du gouvernement ouvert – Canada et l’Open Government Licence v3.0.

Maladies respiratoires

L’activité hebdomadaire de la grippe, de la COVID-19 et du VRS.

  • Famille et carte : respiratory et respiratory-activity
  • À définir : country (us ou gb) et region : un État, un territoire ou DC des États-Unis par nom ou code postal, ou l’Angleterre ou une région de l’UKHSA. Une région vide désigne le pays.
  • Données : pour chaque virus, un niveau de très bas à très élevé, une tendance (à la hausse, stable ou à la baisse, que screenRIG calcule à partir des deux dernières semaines comparées aux deux précédentes), la dernière valeur et 26 semaines d’historique. États-Unis : les niveaux et taux hebdomadaires d’admission à l’hôpital des CDC, actualisés toutes les 6 heures. Angleterre : la part de tests de laboratoire positifs de l’UKHSA, actualisée toutes les 12 heures. L’UKHSA ne publie aucun niveau : screenRIG le fixe en comparant la dernière semaine à la plus haute des 52 dernières : moins de 5 % est très bas, moins de 20 % bas, moins de 40 % modéré, moins de 70 % élevé, et au-delà très élevé.
  • Mention : les CDC, sans aucune approbation de screenRIG par les CDC, le HHS ou le gouvernement des États-Unis et avec le contenu inchangé ; l’UKHSA, selon l’Open Government Licence v3.0.

Almanach

Ce que la carte today ajoute à la date : les fêtes et jours commémoratifs, les événements du jour dans l’histoire, ainsi que le soleil et la lune.

  • Famille et carte : almanac et today
  • À définir : language (ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk ou zh ; en par défaut), country (un code ISO 3166-1), location ({screen.location} le remplit) et date. Une carte sans aucun de ces paramètres affiche l’histoire en anglais et les journées internationales.
  • Données : les jours fériés du pays, ses fêtes et jours commémoratifs et les journées internationales (les noms des jours fériés sont en anglais quelle que soit la langue), jusqu’à dix événements du jour tirés de On This Day de Wikipédia et, avec un lieu, le lever et le coucher du soleil, le midi solaire, l’aube et le crépuscule civils, la durée du jour et la phase de la lune. Le soleil et la lune sont calculés, non récupérés. Le document va de la veille à deux jours plus tard, de sorte qu’une page change à minuit local.
  • Mention : les contributeurs de Wikipédia, selon la licence CC BY-SA 4.0.

Sécurité en plein air

La lecture de chaleur qu’affiche la carte outdoor-safety.

  • Famille et carte : outdoorsafety et outdoor-safety
  • À définir : location.
  • Données : une température au thermomètre-globe mouillé estimée pour un terrain dégagé en plein soleil, calculée à partir de la météo du lieu : température, humidité, vent, nuages et hauteur du soleil. À l’ombre, la lecture est plus basse. C’est une estimation, jamais une mesure de capteur, et le document le dit. Les observations sont horaires : réglez donc staleMinutes de la carte à 120 ou plus.
  • Foudre : le flux ne porte que la chaleur. Réglez show de la carte sur heat, ou écrivez les impacts de foudre dans les données de la carte.

Départs de transport

Les prochains départs de un à quatre arrêts d’un même fournisseur de transport, dans l’ordre de départ.

  • Famille et carte : departures et departures
  • À définir : provider (tfl, entur ou digitransit) et stops, les ID d’arrêt du fournisseur (séparés par des virgules dans l’API). Trouvez un ID avec la recherche d’arrêts du fournisseur.
  • Données : actualisés chaque minute tant qu’un écran affiche le tableau. Un départ annulé reste listé comme annulé, et un arrêt sans départ est un tableau vide. Un arrêt que le fournisseur ne connaît pas fait échouer tout le tableau, et le dernier tableau reste. TfL ne donne que des prévisions en direct : ses lignes n’ont donc aucun retard.
FournisseurExemples d’ID d’arrêtMention
tfl940GZZLUOXC (Oxford Circus), 490008660N (un arrêt d’autobus)Powered by TfL Open Data
enturNSR:StopPlace:337, NSR:Quay:568Contains data under the Norwegian licence for Open Government data (NLOD) distributed by Entur
digitransitHSL:1040129© Digitransit, CC BY 4.0

Vélos en libre-service

Les stations de vélos en libre-service les plus proches d’un lieu, issues de systèmes qui publient GBFS.

  • Famille et carte : bikeshare et bike-share
  • À définir : location ({screen.location} fonctionne) et, facultativement, system, un ID de système MobilityData comme Mobibikes_CA_Vancouver, dublin ou nextbike_bn. Sans system, le système listé le plus proche dont la zone contient le lieu le dessert, et un lieu qu’aucun système listé ne couvre ne donne aucune clé : la carte attend et l’API répond invalid_request à system.
  • Données : les stations les plus proches d’abord, jusqu’à 40 dans un rayon de 20 km, chacune avec vélos, vélos électriques, bornes et statut, actualisées chaque minute.
  • Systèmes : 28 dont le flux porte une licence qui permet la redistribution et l’affichage commercial : Mobi (Vancouver) et City Bikes Helsinki sous ODbL, docomo (Tokyo) sous CC BY 4.0, les systèmes JCDecaux (Dublin, Lyon, Toulouse, Nantes, Bruxelles, Luxembourg, Valence, Ljubljana) sous la Licence Ouverte, et nextbike à Berlin, Cologne, Düsseldorf, Hanovre, Nuremberg, Bonn, Vienne, Linz, Innsbruck, Prague, Brno, Varsovie, Wrocław, Zagreb, Barcelone, Göteborg et Strasbourg sous CC0.
  • Mention : l’exploitant, selon sa licence.

Publier une toile de carte

Suivez Démarrer pour installer le plugin officiel, sélectionner votre projet et jumeler un Player. Créez la carte, placez son identifiant dans une liste de lecture et publiez-la. Cette page utilise la carte indicateur dans la mise en page center.

Enregistrez les propriétés statiques de la carte comme gauge-params.json :

{"theme":"neomustard"}

Créez la carte avec la CLI fournie avec le plugin. Le résultat contient son identifiant crd_.

screenrig card create --type gauge --file gauge-params.json

Ou appelez l’API avec le type et ses paramètres. La réponse 201 contient le id de la carte.

curl --request POST "https://api.screenrig.ai/api/cards" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"type":"gauge","params":{"theme":"neomustard"}}'

Enregistrez ce qui suit comme playlist.json, avec l’identifiant de votre carte à la place de crd_01EXAMPLEGAUGE000000000. L’élément de page n’envoie que l’identifiant et sa mise en page : les params de la carte et ses données restent avec la carte.

{
  "name": "Live gauge",
  "pages": [
    {
      "id": "main",
      "canvas": {
        "width": 1920,
        "height": 1080,
        "background": "#000000FF",
        "viewport_fit": "contain"
      },
      "transition": {
        "type": "crossfade",
        "duration_ms": 500
      },
      "advance": {
        "mode": "duration",
        "after_ms": 15000
      },
      "primitives": [
        {
          "id": "gauge",
          "primitive": "card",
          "card": "crd_01EXAMPLEGAUGE000000000",
          "layout": "center",
          "content_fit": "fill"
        }
      ]
    }
  ]
}

Utilisez l’authentification API pour votre autorisation. Un jeton d’agent nomme déjà son projet, donc les exemples n’envoient pas d’en-tête ScreenRig-Project ; si vous en envoyez un, il doit correspondre au projet du jeton. Gardez les valeurs de jeton hors des fichiers de playlist.

curl --request POST "https://api.screenrig.ai/api/playlists" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data @playlist.json

La réponse identifie la liste de lecture avec un identifiant pl_. Une réponse pending_review attend l’examen du projet avant la mise en ligne. Pour changer les propriétés statiques, mettez à jour la carte avec screenrig card params crd_ID --file gauge-params.json (PATCH /api/cards/{id} avec {"params": {...}}), puis renvoyez le document {name, pages} avec PUT /api/playlists/{id} : la liste de lecture prend les paramètres actuels de la carte lorsqu’elle est enregistrée. Le major d’une carte, facultatif à la création, fixe son contrat ; l’omettre sélectionne la majeure actuelle.

Les anciens éléments de page qui nomment un type du catalogue avec params et data en ligne, ainsi que les routes /api/card-data/{key} qui les servent, sont toujours acceptés. Chaque réponse porte un avertissement de dépréciation qui nomme son remplacement : les identifiants d’instance de carte issus de /api/cards, et /api/cards/{id}/data.

Écrivez les valeurs en direct

Préférez la CLI, qui a la commande. Sauvegardez le document sous gauge-data.json. Le fichier contient le document lui-même, sans enveloppe :

{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}
screenrig card data put crd_01EXAMPLEGAUGE000000000 --file gauge-data.json

Les écritures remplacent tout le document et sont vérifiées par rapport aux propriétés dynamiques de la carte : un document que la carte rejette est refusé avec card_data_invalid (409) et rien ne change. Ajoutez --ttl 30m ou --expires-at INSTANT pour vider les données sur chaque écran, y compris hors ligne, quand rien ne les actualise. Une notification sur la condition card_data_stale informe le projet quand les données d’une carte ont expiré faute de renouvellement.

Ou appelez l’API directement. L’API enveloppe le même document dans un champ document. Les documents sont des objets JSON d’au plus 1 Mio.

curl --request PUT "https://api.screenrig.ai/api/cards/crd_01EXAMPLEGAUGE000000000/data" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"document":{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}}'

Les écrans affichant la carte récupèrent à nouveau le document et le mettent à jour sur place. Lisez un document avec GET /api/cards/{id}/data ; son ETag de révision peut être envoyé comme If-Match à la prochaine écriture. Ajoutez Idempotency-Key pour une écriture répétable en toute sécurité, et ttl_seconds ou expires_at à côté de document pour une expiration. Listez les cartes du projet avec GET /api/cards ; supprimez-en une avec DELETE /api/cards/{id} dès qu’aucune liste de lecture ne l’utilise.

Les images dans les propriétés de carte utilisent media:<mediaId>, référant une image prête dans le même projet. Une écriture de données en direct nécessite que ces images soient approuvées. Ne mettez jamais d’URL d’image dans une propriété de carte.

Assigner et vérifier avec le CLI

Utilisez le CLI intégré du plugin officiel avec le même projet. Prenez l’ID de playlist de la réponse API et l’ID d’écran de screen list, puis assignez et inspectez le résultat :

screenrig screen list
screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE
screenrig screen screenshot scr_EXAMPLE

L’assignation enregistre la liste de lecture désirée. Inspectez les preuves du lecteur avant de rapporter qu’il joue. Référence CLI · Référence API.

Référence de carte

La référence de la carte couvre trois groupes : cartes principales, cartes plein écran et le stinger. Les cartes principales conviennent à toutes les mises en page, les cartes plein écran remplissent tout l’écran, et le stinger joue entre les pages.

Cartes principales

Cartes plein écran

Stinger