Écrans : commandes CLI

Associez un Player avec le code affiché sur son écran.

screen pair <code...> [--name NAME] [--folder ID]

screenrig screen pair "$PAIRING_CODE" --name "Lobby"
screenrig screen pair "$PAIRING_CODE" --folder sfd_01EXAMPLEFOLDER000000000

La réponse porte public_url et l’objet screen jumelé. Le Player termine le jumelage la prochaine fois qu’il contacte le service, sans rien à faire sur l’afficheur : screen show signale state active et online true dès que c’est fait. Après une requête interrompue, relancez la même commande pour réutiliser la clé d’idempotence enregistrée.

Terminer la configuration d’un Player navigateur à partir du code qu’il affiche.

browser setup --code CODE [--open]

screenrig browser setup --code SETUP_CODE --open

La réponse porte code, status (claimed), screen_id et, pour l’écran, player_public_url. Le CLI retient une URL qui échoue à ses vérifications de sécurité, avec l’avertissement player_url_withheld. Un code invalide ou expiré ne crée aucun écran. Après une requête interrompue, relancez la même commande.

Lister les écrans. Les écrans archivés sont omis sauf demande contraire.

screen list [--state archived] [--tag TAG] [--folder ID|root] [--field NAME=VALUE...] [--near LAT,LON,KM]

screenrig screen list --tag Lobby
screenrig screen list --folder sfd_01EXAMPLEFOLDER000000000
screenrig screen list --field region=north
screenrig screen list --near 47.6062,-122.3321,25

Les filtres se combinent. Chaque ligne porte tags, folder_id, fields et location de l’écran lorsqu’ils existent. Avec --human, le tableau n’ajoute une colonne que si un écran listé a la valeur : PLATFORM, REASON (le archive_reason d’un écran archivé), TAGS, FOLDER, FIELDS, LOCATION, ASSIGNED (un écran qui lit autre chose que sa playlist par défaut), HEALTH (un écran qui demande de l’attention) et UPGRADE (un écran dont le Player passe encore à la version de playlist émise, ou n’y est pas parvenu). --state archived liste aussi les écrans qu’un Player a archivés lui-même (device_reset, device_unpair) et les écrans archivés par screen replace (replaced).

Lire un écran, y compris révision, affectation et état de vie.

screen show <id>

screenrig screen show scr_01EXAMPLESCREEN00000000

tags liste les étiquettes de flotte de l’écran. effective_playlist, takeover et playlist_schedule rapportent ce que l’écran joue et pourquoi ; voir Horaires et prise de contrôle. health et les capacités hôtes du Player sont dans Santé et alimentation de l’appareil. online est vrai tant qu’un Player est connecté, incluant une courte fenêtre de reconnexion. Les last_online_at et last_ip optionnels apparaissent après la première connexion. observation optionnel rapporte les surfaces qu’un Player a peintes : id, width, height, pixel_ratio et presentation. Tous ces éléments sont en lecture seule ; screen update ne peut pas les envoyer, et un écran archivé retourne toujours sa ligne.

commands liste les 10 derniers redémarrages, rechargements, vidages de cache, redémarrages d’application et mises à jour de l’écran, du plus ancien au plus récent, chacun avec son type, son state (queued, sent, done, failed, expired, cancelled ou superseded), son source (schedule pour un redémarrage émis par un horaire de redémarrage; absent pour un redémarrage demandé par une personne), son expires_at, et le moment où il a été envoyé ou effectué. reboot_schedule et next_reboot_at indiquent l’horaire de redémarrage de l’écran et le début de sa prochaine fenêtre de redémarrage. Un vidage de cache, un redémarrage d’application ou une mise à jour que le Player a terminé porte aussi son cause et un court detail, que --human affiche dans une colonne CAUSE et une ligne sous le tableau. suspension porte le message et le since d’un écran suspendu. Un écran archivé par screen replace indique replaced_by, l’écran vers lequel son appareil a été déplacé. Avec --human, screen show affiche chacun d’eux.

last_outage indique la dernière panne de l’écran : offline_since, back_at et duration_s, et, une fois qu’un rapport de santé la détermine, une likely_cause parmi device_restart, app_crash, app_restart, network ou platform ; elle est absente lorsque screenRIG ne peut pas la déterminer. Un redémarrage est établi dès le retour de l’écran, tandis qu’une cause réseau ou screenRIG attend le prochain rapport de santé du Player, qui peut prendre jusqu’à quinze minutes. glass porte les verdicts que screenRIG a tirés des rapports de lecture et des captures d’écran. Avec --human, screen show affiche Last outage et Likely cause, ainsi que Playlist stalled, Blank screen ou Frozen picture pour un verdict qui a trouvé un problème ; Notifications précise ce que les verdicts laissent de côté.

folder_id nomme le dossier de l’écran et est absent à la racine du projet. fields, location et wall apparaissent une fois définis : voir screen update et screen wall set. Chaque entrée observation.surfaces porte aussi rotation lorsque le Player peut lire cette valeur, et un mur vidéo signale une entrée par sortie, nommée comme screen wall set les accepte.

manifest_upgrade indique si le Player est passé à la version de playlist qui lui a été émise. Son state vaut none, pending, downloading, preparing, activating, retrying, failed, blocked, partial ou current, à côté de desired_playlist et active_playlist (id, name et revision), soit la dernière version confirmée par le Player, ce qui ne prouve pas que chaque session l’affiche. Une mise à niveau en échec ou partielle porte aussi code, attempt, retry_at et missing_page_count. --human affiche Target v42 · Playing v41. Une mise à niveau échouée ne planifie aucune nouvelle tentative : corrigez la cause, puis exécutez screen reload ou assignez de nouveau la playlist. Une assignation enregistrée ne confirme pas la lecture.

applications_unsupported apparaît tant que le Player jumelé ne peut pas afficher de pages application ou iframe : le manifeste reste inchangé et le Player les ignore. recovery_pending apparaît tant qu’un afficheur ayant perdu son identité enregistrée propose de se reconnecter comme cet écran, avec le expires_at de l’offre ainsi que platform, model, firmware et manufacturer signalés par l’afficheur : voir screen recover.

Modifier en un seul appel le nom, l’assignation de playlist, la substitution du fuseau horaire, les champs ou l’emplacement d’un écran.

screen update <id> [--name NAME] [--playlist-id ID | --clear-playlist] [--timezone ZONE | --clear-timezone] [--field NAME=VALUE...] [--unset-field NAME...] [--clear-fields] [--location LAT,LON [--location-name NAME] [--address TEXT] | --clear-location] [--expect-rev REVISION]

Fournissez au moins l’un de --name, --playlist-id, --clear-playlist, --timezone, --clear-timezone, --field, --unset-field, --clear-fields, --location ou --clear-location.

screenrig screen update scr_01EXAMPLESCREEN00000000 --name "Lobby"
screenrig screen update scr_01EXAMPLESCREEN00000000 --field store_number=0142 --field region=north
screenrig screen update scr_01EXAMPLESCREEN00000000 --location 47.6062,-122.3321 --location-name "Seattle HQ"
screenrig screen update scr_01EXAMPLESCREEN00000000 --clear-playlist --expect-rev 3

En révision, un changement de --playlist-id seul est proposé comme screen assign ; une session Proposer ne peut pas modifier les autres champs.

Modifier les champs ou l’emplacement change la révision du manifeste de l’écran, de sorte qu’un écran qui affiche une playlist prend les nouvelles valeurs. Les cartes et les pages iframe les lisent par écran, de sorte qu’une même playlist affiche les valeurs propres à chaque écran : {screen.field.NAME}, {screen.name} et {screen.timezone} remplissent tout paramètre texte d’une carte, "location": "{screen.location}" remplit l’emplacement d’une carte sous la forme que cette carte attend, et une clé de données de carte peut porter {screen.field.NAME}, comme menu-{screen.field.store_number}. Un écran qui n’a pas un champ affiche ce texte vide, et la carte se passe de cette clé de données ou de cet emplacement. screen show énumère les champs et l’emplacement d’un écran, et screen list trouve des écrans selon ceux-ci. Voir Jetons d’écran dans les adresses iframe et les paramètres d’application.

Créer une nouvelle liste de lecture à partir d’un fichier préparé et l’assigner à un écran.

screen publish <id> <file> [--expect-rev REVISION] [--note TEXT] [--no-wait] [--poll-ms MS] [--timeout MS] [--no-progress]

screenrig screen publish scr_LOBBY lobby.json

Cela crée une nouvelle liste de lecture et l’assigne. Cela ne met pas à jour une liste de lecture existante par nom. Inspectez d’abord le document préparé. Répétez la même entrée pour reprendre un échec ambigu. La relecture de l’assignation ne prouve pas la lecture ; demandez une capture d’écran séparément. En cours d’examen, il retourne stage: pending_review avec les deux examens. Voir Préparer, publier et modifier des listes de lecture.

Après l’assignation, la commande attend que le Player affiche la playlist : data.stage vaut playing et data.playback_verified vaut true. Les changements d’étape s’impriment sur stderr au fur et à mesure, sous forme de lignes JSON ou, avec --human, de texte. Répéter la même commande après une publication terminée signale cette publication (data.already_published) tant que l’écran affiche encore sa playlist, et publie à nouveau dès que l’écran est passé à autre chose.

Dirigez un écran, ou une flotte d’écrans, vers une liste de lecture.

screen assign (<id>... | --tag TAG | --folder ID) --playlist-id ID [--expect-rev REVISION] [--note TEXT]

screenrig screen assign scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --folder sfd_01EXAMPLEFOLDER000000000 --playlist-id pl_01EXAMPLEPLAYLIST000000

Une liste de lecture qui programme des pages s’assigne à n’importe quel écran : les horaires sont lus dans le fuseau horaire propre à l’écran (sa substitution, sinon le fuseau que son appareil rapporte, sinon UTC).

Pour publier sur une flotte, créez la liste de lecture une fois avec playlist create, puis exécutez screen assign --tag TAG --playlist-id ID. screen publish cible un écran.

Avec l’accès Proposer, ou dans un projet qui exige une révision pour les modifications d’agent, la modification d’un seul écran ou de toute la flotte répond plutôt pending_review : data.review porte l’ID de la révision et son url de tableau de bord, un avertissement pending_review donne l’URL, et data.next vaut reviews show ID. Rien ne change à l’écran tant qu’une personne ne l’approuve pas ; ne répétez donc pas l’écriture. Sur un écran dans un dossier protégé, cela répond pending_review à tous les niveaux d’accès, et un approbateur autre que vous et autre que la personne pour qui vous travaillez en décide (sinon second_approver_required, code de sortie 3). Un appelant limité aux dossiers d’écrans n’assigne que sur les écrans de son périmètre. Une assignation enregistrée ne confirme pas la lecture ; screen screenshot montre ce qui est à l’écran.

Remplacer le fuseau horaire dans lequel les règles civiles d’un écran sont lues, ou retirer la substitution.

screen set-timezone <id> (--timezone ZONE | --clear) [--expect-rev REVISION]

screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --timezone America/Los_Angeles
screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --clear

Chaque écran a un fuseau horaire effectif, et chaque règle civile le lit : la visibilité des pages, les emplacements publicitaires, les horaires de liste de lecture, les prises de contrôle, les campagnes, les horaires d’affichage et de redémarrage, et {screen.timezone}. C’est cette substitution, sinon le fuseau que le Player de l’écran rapporte depuis son appareil, sinon UTC. Un écran n’a pas besoin de substitution tant que son appareil rapporte le bon fuseau. screen show affiche le fuseau effectif sous la forme Timezone avec son origine, effective_timezone et timezone_source (screen, device ou default) dans --json. Changer le fuseau effectif recrée la révision du manifeste.

ZONE est au format Area/City, par exemple America/New_York ou Asia/Tokyo, ou UTC.

Définir le mur vidéo d’un écran : un seul Player pilote de deux à douze afficheurs comme un seul canevas.

screen wall set <id> --outputs NAMES --arrangement row|column|grid [--columns N] [--rotation 0|90|180|270] [--expect-rev REVISION]

screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs HDMI-A-1,HDMI-A-2 --arrangement row
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3 --arrangement row --rotation 90 --expect-rev 4
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3,DP-4,DP-5,DP-6 --arrangement grid --columns 3

Un seul Player pilote les afficheurs comme un seul mur, de sorte qu’une page de playlist s’étend sur tous. La définition remplace tout le mur ; répétez donc --rotation et --columns pour les conserver. Seules l’installation kiosque du Player Linux et le Player Windows déclarent la capacité display.wall ; tout autre Player répond wall_unsupported (code de sortie 5) et rien ne change. L’accès Proposer ne peut pas modifier un mur (insufficient_access). Un mur de 2 ou 3 écrans exige Plus ou plus, et un mur de 4 à 12 écrans, Enterprise : un forfait qui ne l’inclut pas répond feature_not_in_plan (sortie 8), tandis que screen wall clear et une configuration qui conserve le mur enregistré restent possibles. Voir Murs vidéo.

Créez la playlist à la forme du mur avec playlist init et l’ID de l’écran, ce qui écrit le canevas correspondant et format (displays, arrangement, orientation et columns pour une grille). Les displays d’une primitive, comme [2] ou [1, 2, 5, 6], nomment les numéros d’afficheur qu’elle couvre, comptés à partir de 1 de gauche à droite puis de haut en bas, et doivent remplir un rectangle du mur. Assigner une playlist dont le format n’est pas la forme du mur donne playlist_format_mismatch (code de sortie 5) ; une playlist sans format se joue de la même façon sur chaque afficheur. Dès que l’écran lit une playlist au format correspondant, chaque afficheur montre son numéro et son nom pendant 20 secondes après un changement, ce qui permet de vérifier l’ordre à l’écran.

Retirer le mur vidéo d’un écran.

screen wall clear <id> [--expect-rev REVISION]

screenrig screen wall clear scr_01EXAMPLESCREEN00000000

La playlist assignée n’est pas revérifiée : si elle possède un format, le manifeste de l’écran se dégrade (wall_format_mismatch) et le Player conserve sa dernière bonne page jusqu’à ce que vous assigniez une playlist sans format. Un écran sans mur répond sans changement. L’accès Proposer ne peut pas modifier un mur (insufficient_access).

Masquer un écran et assombrir sa vitre.

screen archive <id> [--expect-rev REVISION]

screenrig screen archive scr_01EXAMPLESCREEN00000000

L’archivage masque l’écran de la liste par défaut et assombrit la vitre. Il ne désassocie pas le lecteur.

Quiconque détient la clé de l’afficheur peut encore se connecter pendant que l’écran est archivé. Pour mettre du matériel hors service définitivement, laissez l’écran archivé, ou déplacez l’écran vers un nouveau matériel avec screen recover ou screen replace, qui retirent l’ancienne clé.

Restaurer un écran archivé dans la liste par défaut.

screen unarchive <id> [--expect-rev REVISION]

screenrig screen unarchive scr_01EXAMPLESCREEN00000000

Un Lecteur peut aussi archiver son propre écran : une réinitialisation confirmée sur un Lecteur qui détient une clé, ou le déjumelage d’un Lecteur navigateur jumelé par cookie. screen show rapporte alors archive_reason comme device_reset ou device_unpair (project pour une archive que vous demandez), avec archived_at. L’écran conserve son lien d’appareil pour toutes les raisons, donc un Lecteur qui détient encore cette clé ou ce cookie d’appareil reste sombre et reprend à la désarchivation sans nouveau jumelage. Le Lecteur réinitialisé ou déjumelé perd sa clé ou son cookie et se jumelle à nouveau comme un nouvel écran. Une clé remplacée par une récupération d’écran confirmée reste retirée.

Un écran archivé comme replaced par screen replace ne conserve aucun lien d’appareil, donc la désarchivation le refuse et screen delete le supprime.

Afficher un avis sur un écran à la place de son contenu, jusqu’à sa reprise.

screen suspend <id> --message TEXT [--expect-rev REVISION]

screenrig screen suspend scr_01EXAMPLESCREEN00000000 --message "Closed for stocktake. Back at 9am."

Un écran suspendu affiche le message à la place de son contenu. Rien d’autre ne change : sa liste de lecture, son horaire, sa prise de contrôle et le contrôle de l’afficheur restent en place et continuent d’évoluer, et screen resume montre ce que l’écran afficherait en ce moment. screen show rapporte suspension avec le message et le since ; suspendre un écran déjà suspendu remplace le message et conserve since. La suspension augmente la révision de l’écran, et le Player récupère ses données à nouveau immédiatement. Un écran archivé répond screen_archived.

Mettre fin à la suspension d’un écran pour qu’il affiche de nouveau son propre contenu.

screen resume <id> [--expect-rev REVISION]

screenrig screen resume scr_01EXAMPLESCREEN00000000

La reprise affiche de nouveau le contenu propre de l’écran, à partir de ce que l’écran afficherait en ce moment, et le Player récupère ses données à nouveau immédiatement. Un écran qui n’est pas suspendu répond inchangé, sans changement de révision. Un écran archivé répond screen_archived.

Supprimer un écran.

screen delete <id> [--expect-rev REVISION]

screenrig screen delete scr_01EXAMPLESCREEN00000000

Supprimer enlève un écran uniquement tant qu’aucune clé de Player n’y est liée, et screen show rapporte deletable: true pour cet écran. Un Player qui se jumelle par code, Player natif ou Player navigateur, détient une clé, et cette clé reste liée à son écran : supprimer cet écran répond 409 screen_archive_required (code de sortie 5) ; archivez-le plutôt. Seul un Player navigateur jumelé par cookie ne détient aucune clé, et son écran se supprime qu’il soit jumelé ou encore en attente.

Pour jumeler comme nouvel écran un afficheur qui détient une clé, confirmez une réinitialisation sur le Player lui-même, puis réclamez le code qu’il affiche avec screen pair ; l’ancien écran reste archivé. Pour déplacer un écran vers du matériel de remplacement, utilisez screen recover, ou screen replace lorsque ce matériel est déjà jumelé comme son propre écran.

Reconnecter un afficheur qui a perdu son identité enregistrée à l’écran sous lequel il était jumelé.

screen recover <id> [--expect-rev REVISION]

screenrig screen show scr_01EXAMPLESCREEN00000000
screenrig screen recover scr_01EXAMPLESCREEN00000000

Un afficheur qui a perdu son identité enregistrée et signale maintenant les identifiants matériels de cet écran pendant le jumelage fait une offre. screen show la signale comme recovery_pending, avec son échéance et, lorsque l’afficheur les signale, ses platform, model, firmware et manufacturer. Rien n’est rattaché de nouveau tant que cette commande ne le confirme pas : l’écran conserve son libellé, sa playlist, son fuseau horaire, ses horaires et son historique, et la nouvelle clé de l’afficheur remplace la précédente, qui est retirée après un délai de grâce de quinze minutes. Un écran archivé par une réinitialisation de l’appareil reste archivé jusqu’à screen unarchive.

Comparez le modèle et le micrologiciel signalés avec l’afficheur que vous attendez avant de confirmer : toute application exécutée sur un afficheur peut lire ses identifiants, de sorte que l’offre seule ne prouve pas quel afficheur la fait. Le service refuse une offre tant que le Player actuel de l’écran est encore en ligne, et un écran accepte au plus trois offres par heure. Sans offre, la commande répond recovery_not_offered, une offre dont la session de jumelage a expiré répond recovery_expired, et des identifiants rattachés à plus d’un écran répondent recovery_ambiguous ; rien n’est rattaché de nouveau. La récupération ne traverse jamais les projets.

Déplacer l’appareil jumelé en tant qu’autre écran vers cet écran, en conservant les paramètres et l’historique de cet écran.

screen replace <id> --with ID [--expect-rev REVISION]

screenrig screen replace scr_01EXAMPLESCREEN00000000 --with scr_01EXAMPLENEWSCREEN000000

Jumelez d’abord le nouveau matériel comme un écran distinct, puis remplacez. La clé de l’appareil, ou l’identifiant d’un Player navigateur, ouvre désormais <id>, qui conserve son nom, ses étiquettes, son fuseau horaire, sa liste de lecture, ses horaires, sa prise de contrôle, son horaire d’affichage et sa substitution, son mur vidéo, ses commentaires, ses champs, son emplacement et son historique, et reprend l’hôte et le Player de l’écran de remplacement. Sa santé, son statut, son stockage et ses commandes en file d’attente repartent de zéro. L’écran nommé par --with est archivé avec archive_reason replaced et replaced_by nommant <id>. Il ne conserve aucun lien d’appareil, donc screen unarchive ne peut pas le restaurer et screen delete le supprime. La clé que <id> détenait est retirée après une période de grâce de quinze minutes, puis son ancien appareil est refusé. Les deux écrans doivent être actifs avec un Player jumelé : un écran toujours en attente de jumelage répond resource_conflict, un écran archivé répond screen_archived, et un mur vidéo nécessite un Player de remplacement qui déclare display.wall (wall_unsupported). La requête porte toujours une clé d’idempotence, et une nouvelle tentative exacte renvoie la réponse originale.

Pour déplacer un afficheur qui a perdu son identité enregistrée et signale maintenant les identifiants de cet écran, utilisez screen recover.

Émettre un nouvel ID public pour un écran.

screen rotate-public-id <id> [--expect-rev REVISION]

screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

Le public_id de l’écran, l’identifiant dans son URL publique, est remplacé et toute session ouverte avec l’ancien prend fin. Le jumelage du Player est conservé : un Player jumelé ouvre une nouvelle session et continue d’afficher son contenu.

Crée le lien d’un écran, ou le remplace, et affiche son URL de lecteur.

screen link create <id> [--expect-rev REVISION]

screenrig screen link create scr_01EXAMPLESCREEN00000000

Affiche data.url, l’URL du lecteur (https://play.screenrig.ai/player/#screen=…) à coller comme URL d’une source navigateur dans vMix ou OBS, qui ne conserve rien et perdrait sinon son jumelage à chaque chargement. Le lecteur fonctionne depuis l’URL à chaque chargement : l’URL est tout le jumelage. Créer de nouveau le lien le remplace (data.replaced vaut true) : l’ancienne URL cesse de fonctionner aussitôt et le lecteur ouvert depuis elle affiche un avis sans contenu. L’URL est un identifiant d’accès qui ouvre l’écran : elle est affichée sous une étiquette sensible, tenue hors du journal des opérations, et réaffichée par screen link show. Ouvrez-la à un seul endroit. Un écran qui n’est pas jumelé répond resource_conflict (code de sortie 5), et un écran archivé répond screen_archived. Après une requête interrompue, relancez la même commande : elle réutilise la clé d’idempotence enregistrée et renvoie le même lien.

Affiche le lien d’un écran et son URL de lecteur.

screen link show <id>

screenrig screen link show scr_01EXAMPLESCREEN00000000

Affiche data.url sous une étiquette sensible, avec data.hint (les quatre derniers caractères du secret), data.created_at et data.last_used_at une fois qu’un lecteur a ouvert le lien. Un identifiant en lecture seule reçoit url vide avec url_redacted à true, et la sortie lisible indique que l’URL est retenue ; une connexion Manage la reçoit. Un écran sans lien répond screen_link_not_found (code de sortie 4) et nomme la commande qui en crée un. screen show affiche Screen link: on (…HINT) pour un écran qui en a un, jamais son URL.

Désactive le lien d’un écran.

screen link delete <id> [--expect-rev REVISION]

screenrig screen link delete scr_01EXAMPLESCREEN00000000

L’URL cesse de fonctionner aussitôt et chaque session qu’elle a ouverte prend fin : une source navigateur qui l’affiche encore montre un avis et aucun contenu jusqu’à ce qu’on lui donne une nouvelle URL. L’écran, son jumelage et son contenu ne sont pas touchés. La commande réussit sans rien changer lorsque l’écran n’a pas de lien.

Demander au lecteur d’un écran, ou à tous les lecteurs d’une flotte, de recharger une fois.

screen reload (<id>... | --tag TAG | --folder ID) [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen reload scr_01EXAMPLESCREEN00000000
screenrig screen reload scr_01EXAMPLESCREEN00000000 --expires-in 2h
screenrig screen reload --tag Lobby
screenrig screen reload --folder sfd_01EXAMPLEFOLDER000000000

La réponse porte un reload_id, un state et un expires_at. Un écran en ligne reçoit le rechargement immédiatement (state sent) ; un écran hors ligne le conserve queued et le reçoit lorsqu’il revient en ligne avant expires_at, soit 24 heures après la requête sauf indication contraire de --expires-in. Un rechargement plus récent remplace celui qui est toujours en file d’attente ; screen show liste les commands de l’écran, et screen command cancel annule celui qui est toujours en file d’attente. Dans une flotte, le reload de chaque résultat porte le même state. Un lecteur web recharge à sa prochaine limite de page ; un lecteur natif se reconnecte, récupère son manifeste et vérifie une mise à jour. Un lecteur ignore un rechargement dans les dix minutes suivant le dernier traité. Le rechargement fonctionne sur écrans actifs et archivés et ne change pas la révision de l’écran.

Publiez un message transitoire comme chrome de scène sur un écran en direct ou une flotte.

screen toast (<id>... | --tag TAG | --folder ID) --text TEXT [--level info|alert|error] [--duration-ms MS]

screenrig screen toast scr_01EXAMPLESCREEN00000000 --text "Lobby closed"
screenrig screen toast --tag Lobby --text "Closing in ten minutes"
screenrig screen toast --folder sfd_01EXAMPLEFOLDER000000000 --text "Closing in ten minutes"

Un toast n’est pas un primitif : il n’occupe aucun emplacement de canevas, n’a pas de couche, et ne participe pas à la préparation ou au fondu. Le dernier l’emporte, il n’y a pas de file d’attente ni d’annulation, et l’enveloppe acceptée est { expires_at } seulement. Ne mettez jamais d’identifiants ou autre matériel secret dans le texte.

Afficher le nom d’un écran par-dessus son contenu pendant un moment, pour le repérer sur place.

screen identify <id> [--duration DURATION]

screenrig screen identify scr_01EXAMPLESCREEN00000000
screenrig screen identify scr_01EXAMPLESCREEN00000000 --duration 2m

Le Player dessine une superposition plein écran au-dessus de son contenu, avec le nom de l’écran en très grand et son ID en petit au-dessous. La lecture se poursuit par-dessous, et une identification plus récente remplace la superposition. L’enveloppe acceptée porte identify_id, duration_ms et un expires_at à 60 secondes après la requête, de sorte qu’un écran hors ligne ne l’affiche jamais plus tard. Seul un Player qui déclare la capacité identify affiche la superposition : tout autre écran répond 409 identify_unsupported (code de sortie 5) et rien n’est envoyé, donc mettez à jour le Player ou affichez le nom avec screen toast. Un écran archivé répond screen_archived et un écran toujours en attente de jumelage répond resource_conflict. L’identification ne change pas la révision de l’écran.

Lancer une page de la playlist qu’un écran lit actuellement, pour vérifier cette page avec une capture d’écran.

screen play-page <id> --page-id ID

screenrig screen play-page scr_01EXAMPLESCREEN00000000 --page-id welcome
screenrig screen screenshot scr_01EXAMPLESCREEN00000000

La page démarre depuis son début sur le Player de l’écran et la rotation se poursuit à partir de là, de sorte qu’une capture d’écran prise ensuite montre cette page sans attendre la fin de la rotation. La page doit appartenir à la playlist que l’écran lit actuellement : sa prise de contrôle, sinon une campagne en vigueur, sinon son horaire, sinon sa playlist assignée. Toute autre page répond page_not_on_screen (code de sortie 5), et le problème nomme cette playlist. Un Player qui ne déclare pas la capacité play_page dans son rapport d’hôte répond play_page_unsupported (code de sortie 5) et rien n’est envoyé : mettez le Player à jour.

La réponse porte playlist_id, page_id, manifest_revision et expires_at. La requête expire après 60 secondes et ne modifie pas la révision de l’écran. Un écran archivé répond screen_archived et un écran qui attend encore d’être jumelé répond resource_conflict. Une nouvelle tentative avec la même clé d’idempotence rejoue la réponse d’origine.

Capturez une image fixe d’un écran actif, ou de chaque écran d’une flotte, et enregistrez-la sur disque.

screen screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
screen screenshot (<id> <id>... | --tag TAG | --folder ID) [--output DIRECTORY] [--concurrency N] [--timeout MS] [--poll-ms MS]

screenrig screen screenshot scr_01EXAMPLESCREEN00000000 --output ./lobby.webp

screenrig screen screenshot --tag Lobby --output ./lobby-shots

screenrig screen screenshot --folder sfd_01EXAMPLEFOLDER000000000 --output ./north-shots

La commande bloque jusqu’à ce que le WebP soit sur le disque. L’enveloppe indique screen_id, capture_id, path, bytes, sha256, width et height, et jamais les octets de l’image. La dernière demande l’emporte : une demande plus récente remplace une capture en cours. Une capture d’écran de l’application web du Player dessine chaque page iframe comme une tuile gris foncé portant l’étiquette « Page web intégrée » et chaque application telle qu’elle s’affiche elle-même ; l’image ne porte aucun repère de la tuile, de sorte qu’elle ne prouve pas qu’une page iframe s’est affichée.

Avec plusieurs ID, --tag ou --folder, la réponse est un résultat de flotte avec action: "screenshot", le selector et le répertoire output; chaque résultat ok contient path, bytes, sha256, width et height. Avec --tag, la CLI liste d’abord les écrans étiquetés en suivant chaque page de liste; chaque page de liste est une requête d’agent et les captures elles-mêmes ne sont pas comptées, et plusieurs ID n’ont pas besoin de liste. --idempotency-key est refusé sous cette forme, car chaque capture utilise sa propre clé. Si une capture échoue de façon inattendue, le résultat de cet écran est unexpected_error, aucune nouvelle capture ne démarre, les écrans encore en attente signalent not_attempted et le code de sortie est 1.

Pour un seul écran, l’enveloppe porte aussi frame.flat, qui indique si cette image est d’une seule teinte uniforme, et picture, le verdict d’écran vide ou figé lorsqu’il y en a un. Une image uniforme ne constitue pas à elle seule un verdict : une transition entre des pages, ou une page noire exprès, a le même aspect. Avec --folder, la CLI énumère le dossier et chaque dossier qu’il contient, un appel screen list --folder par dossier, et un écran que la liste montre hors ligne est signalé en échec sans capture.

Le serveur admet 10 captures par écran, 30 par organisation et 30 par adresse par minute ; la CLI réessaie les réponses 429 et 5xx avec temporisation progressive et respecte Retry-After. Une capture qui ne peut pas aboutir donne screenshot_unavailable (code de sortie 5) : l’écran est hors ligne, la requête est timed_out, la page affichée contient une surface que le Player ne peut pas capturer (unsupported_surface, comme un iframe tiers visible dans le Player du navigateur), la capture du Player a échoué (capture_failed), ou la capture était encore en attente quand le délai --timeout s’est écoulé. --timeout 0 laisse l’attente au serveur, qui fait expirer une requête sans réponse après 30 secondes. Une capture échouée porte error.display lorsque le Player a signalé son afficheur : power, connected, reported_at et stale (après 35 minutes). Un rapport off ou standby récent suggère de réessayer lorsque l’afficheur est allumé.

Démarrer la vue en direct d’un écran, ou la renouveler, et afficher la page du tableau de bord qui la montre.

screen live start <id> [--duration DURATION] [--wait DURATION]

screenrig screen live start scr_01EXAMPLESCREEN00000000
screenrig screen live start scr_01EXAMPLESCREEN00000000 --duration 2m --wait 60s

La vue en direct montre dans le tableau de bord, en vidéo, ce qu’un écran lit ; la CLI démarre, lit et arrête la session et ne transporte jamais la vidéo. data contient la session avec viewer_url, la page à ouvrir. Démarrer un écran qui a une session la renouvelle : la durée accordée devient la plus tardive entre sa fin actuelle et --duration à partir de maintenant, sans jamais dépasser cinq minutes après le début de la session. Ensuite la session se termine d’elle-même : rien ne la renouvelle ni ne la redémarre, et la session suivante exige un nouveau screen live start. Elle se termine plus tôt lorsque la durée accordée s’écoule, à l’exécution de screen live stop, ou lorsque le Player y met fin.

La commande demande au Player de publier et lit la session chaque seconde pendant la durée fixée par --wait, jusqu’à ce que le Player signale qu’il est connecté. Si le Player n’est pas connecté à la fin de l’attente, la réponse reste ok avec l’avertissement live_not_ready : relisez screen live status, ou ouvrez viewer_url. Une session terminée pendant l’attente donne live_unavailable (code de sortie 5) et son détail nomme ended_reason, par exemple consent_timeout (sur Android, une personne devant l’écran autorise la capture de l’écran une fois à chaque démarrage du Player). Un écran hors ligne donne aussi live_unavailable, et un écran archivé répond screen_archived. Un Player qui ne déclare pas la capacité live_view répond live_unsupported (code de sortie 5) et rien n’est envoyé : mettez le Player à jour. Un serveur sans relais média répond feature_unavailable : utilisez screen screenshot. La vue en direct est gratuite. Voir Vue en direct.

Lire la session de vue en direct d’un écran.

screen live status <id>

screenrig screen live status scr_01EXAMPLESCREEN00000000

state vaut idle (aucune session), requested (le Player a été sollicité), publishing (le relais détient sa vidéo) ou ended, avec ended_reason pendant dix minutes. publisher.connected est le rapport du Player lui-même, vieux de 45 secondes au plus, et n’est pas la preuve qu’une image s’affiche. data inclut viewer_url.

Terminer la session de vue en direct d’un écran.

screen live stop <id>

screenrig screen live stop scr_01EXAMPLESCREEN00000000

Termine la session et demande au Player d’arrêter de publier, puis affiche la session telle qu’elle est : ended avec ended_reason stopped. La commande réussit lorsqu’il n’y a aucune session. Une session se termine aussi d’elle-même lorsque sa durée accordée s’écoule.

Enregistrer des images JPEG de ce qu’un écran lit, à partir de son flux en direct, pour vérifier la lecture et le mouvement.

screen live frame <id> [--output PATH] [--count N] [--interval DURATION] [--duration DURATION] [--wait DURATION] [--stop]

screenrig screen live frame scr_01EXAMPLESCREEN00000000
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output now.jpg --stop
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output frames/ --count 5 --interval 1s

La commande démarre la session en direct, attend que le Player publie, demande des images au relais média et lit chaque nouvelle image une seule fois. Une image est la vidéo telle que l’encodeur du Player l’a envoyée, réduite à 1280x720 au plus et avec perte, environ une par seconde : elle montre le mouvement et ce qui est à l’écran maintenant, alors comparez des images (--count 5 --interval 1s) pour vérifier que le contenu bouge. Ce n’est pas une capture d’écran, qui reste la preuve de la mise en page. Les images sont gratuites.

data contient {screen_id, live_id, frames}, avec path, captured_at, width, height, bytes et sha256 par image, et stopped true lorsque --stop a mis fin à la session. Sans --stop, la session est laissée à sa durée accordée. Un Player qui ne publie pas dans le délai fixé par --wait, ou qui n’envoie aucune nouvelle image dans ce délai, donne live_not_ready (code de sortie 5) ; sur Android, une personne devant l’écran autorise la capture de l’écran une fois à chaque démarrage du Player. Une session terminée, ou dont les images ont cessé d’arriver, donne live_unavailable (code de sortie 5). Un Player sans la capacité live_view répond live_unsupported, et un serveur sans relais média ou sans images répond feature_unavailable (code de sortie 4) : utilisez screen screenshot.

Définir, ajouter, supprimer ou effacer les étiquettes sur un écran ou une flotte.

screen tag (<id>... | --tag TAG | --folder ID) (--set TAGS | --add TAGS | --remove TAGS | --clear) [--expect-rev REVISION]

screenrig screen tag scr_01EXAMPLESCREEN00000000 --set Lobby,Floor2
screenrig screen tag scr_01EXAMPLESCREEN00000000 --add Spring
screenrig screen tag --tag Lobby --add Spring
screenrig screen tag --folder sfd_01EXAMPLEFOLDER000000000 --add Spring

Une étiquette fait de 1 à 32 lettres ou chiffres, et un écran porte au plus 16 étiquettes uniques. Les étiquettes sélectionnent des flottes ; elles ne sont jamais une autorisation et n’atteignent jamais le Player. Changer les étiquettes augmente la révision de l’écran, pas celle du manifeste. Pour un écran, l’enveloppe est l’écran mis à jour. --add et --remove lisent d’abord l’écran et écrivent le nouvel ensemble protégé par --expect-rev ou la révision juste lue, donc un changement concurrent renvoie revision_conflict (sortie 6) au lieu d’être écrasé ; relancez la commande. Dans une flotte, --add et --remove s’appliquent atomiquement à l’ensemble stocké de chaque écran, et un écran qui dépasserait 16 étiquettes échoue dans son propre résultat avec invalid_request.

Chaque fois que des étiquettes changent (screen tag, une mise à jour d’écran par l’API, l’éditeur d’étiquettes du tableau de bord), levels dans la réponse liste, sous gained et lost, les campagnes dont l’audience d’étiquettes l’écran a rejointe ou quittée, chacune avec son source (campaign), son id, le nombre de screens et, quand la campagne a une portée, reach_before et reach_after. Un screen tag de flotte les additionne sur la flotte. Lisez levels.lost avant de juger une modification d’étiquette inoffensive : retirer la dernière étiquette correspondante des écrans d’une campagne vide ce groupe et déclenche les notifications reach_dropped et group_empty.

Déplacer des écrans et des dossiers d’écrans dans un dossier d’écrans, ou de nouveau à la racine du projet.

screen move <id>... (--folder ID | --root) [--note TEXT]

screenrig screen move scr_01EXAMPLESCREEN00000000 --folder sfd_01EXAMPLEFOLDER000000000
screenrig screen move sfd_01EXAMPLEFOLDER000000000 --root

Le déplacement est une seule requête tout ou rien. Un dossier se déplace avec tout son contenu et ne peut pas être déplacé dans lui-même ni dans un dossier qu’il contient ; les dossiers s’imbriquent sur 10 niveaux au maximum. Les éléments déjà dans la destination restent tels quels et ne sont pas comptés. data.screens et data.folders comptent ce qui a été déplacé. data.levels énumère, sous gained et lost, les campagnes dont l’audience de dossier a accueilli ou perdu les écrans déplacés (source campaign, avec reach_before et reach_after) et les playlists par défaut de dossier qu’ils ont commencé ou cessé d’afficher (source folder). Les écrans recalculent leur playlist en 15 secondes environ ; screen show indique effective_playlist, et campaign explain SCREEN_ID explique pourquoi.

Un appelant limité aux dossiers d’écrans ne déplace que des écrans et des dossiers de son périmètre vers un dossier de son périmètre ; tout autre cas, y compris la racine du projet, fait refuser tout le déplacement avec outside_screen_scope (code de sortie 3). Un déplacement vers un dossier protégé ou hors d’un dossier protégé répond pending_review avec une révision protected_change que décide un second approbateur ; ne répétez donc pas l’écriture ; --note indique à l’approbateur pourquoi. Après une requête interrompue, relancez la même commande pour réutiliser la clé d’idempotence enregistrée.

Lister les dossiers d’écrans du projet sous forme d’arborescence, avec les écrans actifs directement dans chacun et sa playlist par défaut.

screen folder list

screenrig screen folder list

Renvoie chaque dossier d’écrans du projet, 1000 au maximum, classés par nom. data.items porte pour chaque dossier id, name, parent_id (null à la racine du projet), default_playlist_id lorsqu’il est défini, protected lorsqu’il est défini, screens (les écrans actifs directement à l’intérieur, et non ceux des dossiers en dessous) et revision. Avec --human, la sortie est l’arborescence, une ligne par dossier avec son chemin. Le dossier d’un écran est folder_id sur screen list et screen show, absent à la racine du projet. L’accès en lecture seule suffit.

Examiner un dossier d’écrans.

screen folder show <id>

screenrig screen folder show sfd_01EXAMPLEFOLDER000000000

Renvoie un dossier avec les champs que renvoie screen folder list. L’accès en lecture seule suffit.

Créer un dossier d’écrans à la racine du projet ou dans un autre dossier.

screen folder create --name NAME [--parent ID] [--default-playlist-id ID] [--note TEXT]

screenrig screen folder create --name "North Tower"
screenrig screen folder create --name "Level 2" --parent sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000

Une organisation contient au plus 1000 dossiers dans l’ensemble de ses projets (quota_exceeded), imbriqués sur 10 niveaux au maximum (invalid_request). Placez-y des écrans avec screen move. Un dossier cible ensuite ses écrans dans les commandes de flotte et comme audience de campagne : voir Dossiers d’écrans.

Un appelant limité aux dossiers d’écrans ne crée des dossiers que dans son périmètre : --parent doit être l’un de ses dossiers (outside_screen_scope, code de sortie 3). Un dossier créé dans un dossier protégé répond pending_review avec une révision protected_change que décide un approbateur autre que vous et autre que la personne pour qui vous travaillez ; ne répétez donc pas l’écriture ; --note indique à l’approbateur pourquoi. Après une requête interrompue, relancez la même commande pour réutiliser la clé d’idempotence enregistrée.

Renommer un dossier d’écrans, le déplacer avec tout son contenu, ou définir ou effacer sa playlist par défaut.

screen folder update <id> [--name NAME] [--parent ID | --root] [--default-playlist-id ID | --clear-default] [--expect-rev REVISION] [--note TEXT]
screen folder update <id> --unprotect [--expect-rev REVISION] [--note TEXT]

Fournissez au moins l’un de --name, --parent, --root, --default-playlist-id, --clear-default ou --unprotect.

screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --name "Northern"
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --root
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000 --expect-rev 3
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --clear-default
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --unprotect --note "Menu boards move next week"

Un dossier ne peut pas être déplacé dans lui-même ni dans un dossier qu’il contient, et les mêmes valeurs ne changent rien. Un déplacement ou un changement de playlist par défaut fait recalculer leur playlist aux écrans à l’intérieur en 15 secondes environ, et data.levels énumère les campagnes dont l’audience de dossier a accueilli ou perdu ces écrans (source campaign) et les playlists par défaut de dossier qu’ils ont gagnées ou perdues (source folder).

Un renommage reste possible sur un dossier protégé. Le déplacement, ou la playlist par défaut, d’un dossier protégé ou qui en contient un répond pending_review avec une révision protected_change que décide un second approbateur (un approbateur autre que vous et autre que la personne pour qui vous travaillez ; sinon second_approver_required, code de sortie 3). Rien ne change d’ici là ; ne répétez donc pas l’écriture ; --note indique à l’approbateur pourquoi. Une personne qui peut approuver protège un dossier dans le tableau de bord ; la CLI propose seulement de retirer la protection avec --unprotect. Voir Dossiers protégés. Un appelant limité aux dossiers d’écrans ne modifie que des dossiers dans son périmètre et ne les déplace que vers un parent qui s’y trouve (outside_screen_scope, code de sortie 3), et jamais la protection d’un dossier que son périmètre nomme.

Supprimer un dossier d’écrans ; ses écrans et dossiers remontent d’un niveau.

screen folder delete <id> [--expect-rev REVISION] [--note TEXT]

screenrig screen folder delete sfd_01EXAMPLEFOLDER000000000
screenrig screen folder delete sfd_01EXAMPLEFOLDER000000000 --expect-rev 3

Supprime seulement le dossier : ses écrans et dossiers remontent dans son parent (la racine du projet s’il n’en a pas) et ces écrans recalculent leur playlist. data contient id, deleted true et levels, les campagnes et playlists par défaut de dossier que les écrans déplacés ont gagnées ou perdues, avec reach_before et reach_after d’une campagne. Une audience de campagne qui nomme le dossier refuse la suppression avec resource_conflict (code de sortie 5) : modifiez ou supprimez d’abord ces campagnes.

Un appelant limité aux dossiers d’écrans ne supprime que des dossiers dans son périmètre, jamais un dossier que son périmètre nomme (outside_screen_scope, code de sortie 3). Un dossier qui est un dossier protégé ou qui en contient un répond pending_review avec une révision protected_change que décide un second approbateur ; ne répétez donc pas l’écriture ; --note indique à l’approbateur pourquoi.