Choisissez le chemin de création approprié

Regarder sa construction

Film / Créer une application kiosque avec le SDK

3:07

Utilisez screenrig après la configuration de la session sur Démarrer.

Choisissez le chemin du contenu

La génération compose l’illustration et la typographie ensemble : mettez donc tout le texte dans l’invite. Les cartes affichent leur texte dans le Player, donc un mot ou un nombre modifié ne demande pas de nouvelle image fixe. Les ressources terminées fournies n’ont pas besoin de génération. L’animation seule n’exige ni l’une ni l’autre.

Générer une image fixe finalisée

L’agent envoie une invite plus aspect_ratio et quality. screenRIG renvoie un objet média med_… dans la boutique de médias du compte. L’appelant ne téléverse pas à nouveau les octets. Récupérez les octets originaux uniquement pour inspection ; sinon, conservez la référence med_… dans une liste de lecture.

Votre propre media upload reste valide. Ne générez pas lorsque vous avez déjà le fichier. Les pages de vidéo en direct, de flux, d’iframe et d’app web sont des primitives de liste de lecture, pas des images fixes générées.

La qualité est low, medium, ou high (par défaut medium). Le format d’image est 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, ou 2:3 (par défaut 16:9). --quality change le niveau de détail de l’image fixe et donc le nombre de jetons utilisés :

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality QUALITY] [--tag TAG]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

L’enveloppe rapporte un identifiant med_…. Elle n’imprime jamais d’octets d’image.

{
  "ok": true,
  "data": {
    "id": "med_01EXAMPLEGENERATED0000000",
    "media_id": "med_01EXAMPLEGENERATED0000000"
  }
}

Ajouter une bande sonore

Une liste de lecture peut porter une bande sonore : une liste ordonnée de pistes MP3 qui joue continuellement pendant que les pages changent. Les transitions de page ne stoppent, ne redémarrent ni ne fondent la musique. La bande sonore est un paramètre de liste de lecture, pas un septième primitif, donc elle n’a ni rectangle ni couche sur la toile.

Téléversez chaque piste avec media upload. Les fichiers MP3 sont téléversés tels quels ; les fichiers WAV, AAC, M4A, OGG et FLAC sont d’abord transcodés en MP3. Chaque piste devient un objet média audio avec un identifiant med_… et une durée.

screenrig media upload ./intro.mp3 --tag LobbyMusic
screenrig media upload ./bed.wav --tag LobbyMusic

Nommez les pistes dans la liste de lecture audio membre ; elle contient de 1 à 128 pistes. Les pistes jouent dans l’ordre, les unes à la suite des autres. loop (par défaut true) recommence à la première piste après la dernière ; volume (par défaut 1, de 0 à 1) ajuste le volume propre du Player.

{
  "name": "Lobby",
  "audio": {
    "tracks": [
      { "id": "intro", "media_id": "med_01EXAMPLEINTRO000000000" },
      { "id": "bed", "media_id": "med_01EXAMPLEBED00000000000" }
    ],
    "loop": true,
    "volume": 0.8
  },
  "pages": [
    { "id": "welcome", "audio_cue": { "track": "intro", "restart": true } },
    { "id": "menu" }
  ]
}

Une page peut porter un audio_cue optionnel. Quand cette page apparaît, le Player passe à la piste nommée depuis son début ; si cette piste joue déjà, elle redémarre seulement si restart est true. La séquence continue alors depuis la piste lancée. Les repères sont des indices : un Player les applique avec un fondu court ou les ignore si la piste n’est pas prête. Les pages sans repère laissent la musique telle quelle. Les champs de page autres que id et audio_cue sont omis dans l’exemple ci-dessus.

Remplacer une liste de lecture remplace aussi sa bande sonore ; laissez audio de côté pour la supprimer. Les vidéos sur la toile restent muettes, donc la bande sonore est le seul son joué par un écran.

Lier une page à une piste

Pour un album ou un livre avec une page par piste, ou toute page qui dure exactement aussi longtemps qu’une piste, liez la page à sa piste.

Définir la page advance sur { "mode": "audio_end" }. La page applique son audio_cue quand elle apparaît, comme tout déclencheur, et se termine quand cette piste se termine, de la même façon qu’une page media_end se termine avec sa vidéo. La page doit porter un audio_cue et la liste de lecture une bande sonore audio. Les primitives image et vidéo suivent les règles duration : pas de dwell_ms, et one_at_a_time: true sur chaque sélecteur dynamique (all, tag, folder ou ids avec plus d’un id), même si cela correspond à un seul objet aujourd’hui. Une primitive stream nécessite toujours une page duration, et une application sur la page n’est jamais son contrôleur. max_ms est un indice de sécurité optionnel ; le serveur fixe la date limite selon la durée de la piste, donc omettez-le. Si le lecteur ne peut pas jouer la piste, la page dure quand même la durée de la piste.

Définir cued sur true dans le membre audio pour arrêter la bande sonore après chaque piste. Une piste mise en attente ne joue que lorsqu’une page audio_cue la démarre. Elle continue de jouer sous toutes les pages ordinaires qui suivent sa page jusqu’à sa fin, puis la bande sonore est silencieuse jusqu’au prochain déclenchement, de sorte qu’une page et sa piste restent liées, avec n’importe quel nombre de pages ordinaires entre les pages liées. loop n’a aucun effet sur une bande sonore mise en attente, et cued est par défaut false.

{
  "name": "Album",
  "audio": {
    "tracks": [
      { "id": "song1", "media_id": "med_01EXAMPLESONG1000000000" },
      { "id": "song2", "media_id": "med_01EXAMPLESONG2000000000" }
    ],
    "cued": true
  },
  "pages": [
    { "id": "song1-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song1", "restart": true } },
    { "id": "interlude", "advance": { "mode": "duration", "after_ms": 8000 } },
    { "id": "song2-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song2", "restart": true } }
  ]
}

Les champs de page autres que id, advance et audio_cue sont omis de l’exemple ci-dessus.

Placer une carte pour du texte en direct

Une carte intégrée affiche du texte, un menu, un tableau, une horloge ou une jauge dans le Player lui-même : le texte reste modifiable et une nouvelle valeur atteint chaque écran sans nouvelle image fixe. cards list affiche les types, card create crée une instance, et la liste de lecture la place comme primitive card. card data put écrit ses valeurs en direct. Cartes liste chaque type et chaque mise en page.

screenrig cards list
screenrig card create --type gauge --file gauge-params.json
screenrig card data put crd_EXAMPLE --file gauge-data.json

Afficher un tableau de bord derrière une connexion

Une connexion web ouvre une session sur un site comme le ferait une personne, avec un compte de service, et une vue web affiche une page de ce site. Elle convient aux tableaux de bord de Salesforce, Looker Studio, Datadog, HubSpot et de tout autre site sans lien public. Un navigateur situé en périphérie de screenRIG ouvre la page en étant connecté et le Player en affiche une image, redessinée toutes les refresh_s secondes (de 60 à 86 400, 300 par défaut). Tous les écrans de même taille partagent une seule image : ajouter des écrans n’ajoute donc aucune connexion, et une image n’est dessinée que lorsque la liste de lecture d’un écran affiche la vue. Les connexions et vues Grafana, Power BI et Tableau fonctionnent de la même façon et figurent dans la référence de l’API.

1. Créez un compte de service sur le site, qui ne peut lire que les tableaux de bord que vos écrans affichent. Chaque capture se connecte sous ce compte.
2. Créez la connexion avec kind web et les paramètres ci-dessous. Le mot de passe est secret.
3. Créez une vue d’une page : son adresse https comme url et, comme wait_for, un sélecteur CSS d’un élément qui n’apparaît que lorsque la page est connectée et prête, de sorte qu’une page de connexion expire au lieu d’être dessinée. clip ne dessine que la partie de la page que nomme un sélecteur, et wait_ms (jusqu’à 10 000) attend les graphiques tardifs.
4. Placez le embed_url de la vue dans une primitive iframe avec content_fit fill.

{
  "kind": "web",
  "name": "Sales dashboard",
  "config": {
    "login_mode": "auto",
    "login_url": "https://login.example.com/sign-in",
    "username": "screens@example.com"
  },
  "secret": "ACCOUNT_PASSWORD",
  "totp_secret": "AUTHENTICATOR_KEY"
}

{
  "connection_id": "bic_01EXAMPLECONNECTION0000",
  "name": "Sales this week",
  "url": "https://app.example.com/dashboards/sales",
  "refresh_s": 300,
  "wait_for": "#sales-total"
}

Le mot de passe, la clé TOTP et les cookies se placent à côté de config, sont stockés chiffrés et ne sont plus jamais affichés : une lecture indique si chacun est défini. Un secret ou totp_secret vide, ou cookies: [], le supprime.

• Les cookies passent d’abord. La connexion garde un seul fichier de cookies chiffré : celui que vous avez collé, puis les cookies que renvoie chaque capture. Une capture envoie le fichier de cookies et aucun identifiant, et ne se connecte que s’il n’y a pas de fichier ou si la dernière capture a atteint une page de connexion. Un site qui garde sa session hors des cookies exige une connexion à chaque capture : donnez donc à sa vue un refresh_s long.
• Le mot de passe va seulement à la page de connexion. Il est saisi à login_url et dans les étapes goto, jamais dans l’adresse d’une vue. Ajouter une adresse à l’un ou l’autre exige le mot de passe dans la même requête : un membre qui ne peut pas lire le mot de passe ne peut donc pas le diriger vers une page à lui.
• Le compte est protégé. Une connexion refusée (bi_web_login_failed ou bi_web_otp_required) attend 5 minutes, puis 15, 60 et 120, et la cinquième de suite arrête la connexion jusqu’à ce que vous changiez ses identifiants ou ses paramètres de connexion : au plus 3 tentatives ont donc lieu la première heure. Une ouverture de session qui se termine autrement (délai dépassé, blocage, page qui ne s’ouvre pas) attend 15 minutes. Utilisez un compte de service en lecture seule.
• Certains sites ne peuvent pas être scriptés. Un site qui approuve les connexions sur un téléphone, vérifie les appareils ou affiche un CAPTCHA exige un fichier de cookies (login_mode none) ou un compte de service que le site exempte.

Le Player garde la dernière bonne image pendant l’échec d’une capture, et le statut de la vue porte l’un de ces codes :

screenrig bi connection test ID ouvre une session et rapporte le résultat. Le session d’une connexion indique où en sont ses cookies et sa connexion : idle, active, login_needed, paused, stopped ou expired.

Filtres d’étiquettes et lots de lecture

Les médias portent jusqu’à 32 étiquettes uniques, chacune de 1 à 32 lettres ou chiffres. Remplacez l’ensemble complet par screenrig media update med_ID --tags Summer,Drinks. --tag Summer le remplace par une étiquette ; --clear-tag efface toutes les étiquettes. media list --tag Summer correspond à l’appartenance n’importe où dans l’ensemble. Les étiquettes sont sensibles à la casse et ne sont jamais une autorisation.

Un sélecteur dynamique peut utiliser un tag ou un objet filtre tags :

{
  "by": "tag",
  "tags": { "all": ["Summer", "Drinks"], "any": ["Lobby", "Patio"], "none": ["Expired"] },
  "order": "random",
  "one_at_a_time": false,
  "batch_size": 3
}

all exige toutes les étiquettes listées, any en exige au moins une, et none exclut toute étiquette listée. Les groupes présents se combinent avec ET ; les groupes omis n’imposent aucune condition. Fournissez au moins un groupe non vide. Chaque groupe accepte jusqu’à 32 étiquettes uniques. tag et tags sont mutuellement exclusifs. Un filtre uniquement none sélectionne tous les médias prêts de ce primitif sauf les étiquettes exclues. Les sélecteurs d’image sélectionnent des images et les sélecteurs vidéo sélectionnent des vidéos.

Le bassin de candidats contient jusqu’à 1 024 médias prêts par sélecteur, avec 1 024 références médias dans l’instantané complet de la boucle. Un appariement plus grand renvoie une erreur ; affinez les filtres. batch_size est une limite distincte de 1 à 1 024 éléments par visite de page. Sur une page media_end, one_at_a_time: false joue le lot suivant dans la séquence ; omettre batch_size joue le reste du passage. one_at_a_time: true joue un élément par apparition et permet seulement une taille de lot omise ou batch_size: 1. La durée, l’application et les pages audio_end nécessitent one_at_a_time: true. Les images sur media_end nécessitent aussi dwell_ms ; les vidéos ne peuvent pas boucler sur cette page.

Le lecteur résout chaque primitive média dynamique en une seule requête au démarrage de la liste de lecture et à chaque limite de boucle. L’appartenance est figée pendant la boucle. Les téléversements, suppressions, changements d’étiquetage et bornes de disponibilité ne régénèrent pas le manifeste. Au prochain rafraîchissement, les éléments supprimés ou nouvellement exclus quittent la file d’attente en attente ; les nouvelles correspondances rejoignent à la fin du passage actuel. Un lot final peut contenir moins que le nombre demandé ; il ne se remplit pas au passage suivant. L’ordre des noms de fichiers trie par nom, puis par ID média. L’ordre aléatoire mélange une fois par passage complet, en conservant l’ordre restant aux rafraîchissements de boucle. L’ordre pondéré suit ses poids, plus bas. Le curseur est local à l’écran, la liste de lecture, la page et la primitive, persiste au redémarrage, et se réinitialise quand le filtre, l’ordre ou la politique de lot change. La lecture hors ligne utilise le dernier instantané réussi. Les correspondances vides sautent la primitive et toute page vide résultante.

Enregistrez l’objet sélecteur ci-dessus sous selector.json, puis inspectez son catalogue de candidats actuel avant publication :

screenrig media selector-preview selector.json --primitive video

L’aperçu renvoie matched_count, ordonné par nom de fichier candidates avec les ID médias et les balises, ainsi que la politique selector normalisée. En ordre aléatoire, il affiche la piscine et la politique de mélange ; il ne choisit pas le mélange du lecteur, n’avance pas un curseur, ne crée pas de droit de lecture ni ne modifie un manifeste. En ordre pondéré, il renvoie pour chaque candidat weight et share_percent, ainsi que cycle. --rect WxH (API rect: {width, height}) est la taille de l’emplacement et est obligatoire avec fit: "aspect" ; les correspondances écartées sont listées dans excluded avec la raison aspect_mismatch. Les sélecteurs d’images passent --primitive image. L’API est POST /api/selectors/preview avec { "primitive": "video", "selector": ... }. Elle utilise le projet authentifié et les mêmes règles de correspondance que la lecture. Les modifications du catalogue après l’aperçu sont résolues à la prochaine limite de boucle de la lecture.

L’exportation de paquet statique fige les correspondances dynamiques en identifiants exacts. Elle préserve la lecture un à la fois ou en passage complet ; une séquence d’exécution bornée utilisant batch_size avec one_at_a_time: false nécessite de retirer ce champ ou de choisir des identifiants explicites avant l’exportation. Cela évite de perdre silencieusement un curseur de lot d’exécution dans un paquet statique.

Rotation pondérée et ajustement au format

order: "weighted" fait tourner les créations d’un emplacement selon leur poids, de sorte que chaque commanditaire conserve sa part de lectures. weights associe un ID média (med_...) ou tag:NAME à un entier de 1 à 1 000, avec au plus 64 clés. Il fonctionne avec by valant all, tag ou folder :

{
  "by": "all",
  "order": "weighted",
  "one_at_a_time": true,
  "weights": { "tag:Acme": 50, "tag:Globex": 30, "tag:Initech": 20 },
  "fit": "aspect"
}

Des poids de 50, 30 et 20 livrent exactement 5, 3 et 2 lectures sur 10, à chaque cycle, et un redémarrage reprend en milieu de cycle. Le poids d’un élément est sa clé d’ID média lorsqu’elle est présente ; sinon la première clé tag:NAME, par ordre alphabétique, parmi les balises qu’il porte, répartie également entre les éléments de la sélection qui la portent, de sorte que la part d’un commanditaire reste la même quel que soit son nombre de créations ; sinon l’élément forme son propre groupe avec un poids de 1. Un cycle compte au plus 4 096 lectures ; les parts sont arrondies à ce nombre seulement lorsque le ratio exact exige un cycle plus long.

L’ordre pondéré lit un élément par visite : définissez one_at_a_time: true ou batch_size: 1. weights est obligatoire avec l’ordre pondéré et n’est permis qu’avec lui ; sinon l’écriture renvoie invalid_request. Les lecteurs Web, Android, Apple, Windows et Linux prennent en charge l’ordre pondéré à partir des versions qui déclarent la capacité d’hôte selector.weighted. Un lecteur plus ancien lit le sélecteur en ordre aléatoire, et les diagnostics du manifeste portent selector_order_downgraded.

fit: "aspect" sur un sélecteur dynamique ne garde que les fichiers dont le rapport largeur/hauteur est à moins de 5 % de celui du rectangle de l’emplacement, mur vidéo ou cadre d’affichage compris, lu au moment où le sélecteur se résout. Un emplacement en portrait ne lit jamais un fichier en paysage. Aucun changement de lecteur n’est nécessaire.

screenrig media selector-preview affiche la part attendue de chaque sélecteur pondéré ou ajusté au format, et l’éditeur de pages du tableau de bord montre le même tableau dans l’inspecteur. L’exportation de paquet statique fige un sélecteur pondéré en identifiants exacts dans l’ordre des noms de fichiers ; les poids ne sont pas conservés.

Jetons d’écran dans les sélecteurs de balises

Le tag d’un sélecteur de balise, et chaque entrée de son filtre tags, peut être {screen.field.NAME} ou {screen.id}, l’identifiant de l’écran sans son préfixe scr_, qui est une balise. Le serveur renseigne le jeton pour chaque écran lorsqu’il construit le manifeste et l’instantané de sélecteur de cet écran : une seule liste de lecture lit donc les médias propres à chaque écran. Étiquetez les médias Lobby ou Garage, définissez le champ de chaque écran avec screenrig screen update scr_ID --field zone=Lobby, puis donnez ce sélecteur à l’emplacement :

{ "by": "tag", "tag": "{screen.field.zone}", "one_at_a_time": true }

La valeur renseignée suit les règles des balises : 1 à 32 lettres ou chiffres. Un écran sans le champ, ou dont la valeur n’est pas une balise, ne sélectionne rien : il ne lit aucun fichier de cet emplacement, et les diagnostics du manifeste portent screen_fact_missing ou screen_fact_invalid. Modifier un champ régénère le manifeste de cet écran. Un sélecteur avec jeton ne peut pas être prévisualisé (media selector-preview attend une balise concrète) ni figé par playlist export.

Jetons d’écran dans les adresses d’iframe et les params d’application

Le src et le fallback_src d’un iframe peuvent porter des jetons d’écran dans le chemin, la requête ou le fragment d’une adresse http ou https, tout comme le params facultatif d’une primitive application : jusqu’à 16 noms de 1 à 32 lettres minuscules, chiffres ou traits de soulignement (ticket et policy sont réservés) avec des valeurs d’au plus 512 caractères. Le serveur les remplit pour chaque écran :

{
  "primitive": "iframe",
  "src": "https://maps.example.com/directory?kiosk={screen.field.kiosk_id}&level={screen.field.level}",
  "title": "Directory"
}

L’écriture stocke le modèle tel qu’écrit, accolades comprises. Le manifeste de chaque écran porte sa propre adresse, chaque valeur encodée en pourcentage pour son emplacement dans l’URL : un kiosk_id de B 2&3 devient B%202%263. Un jeton dans le schéma, les identifiants, l’hôte ou le port, ou dans un lien YouTube, un lien de document Google ou Microsoft ou une adresse de vue BI, est invalid_request à src (ou fallback_src). La publication omet la vérification d’encadrement pour un src modélisé, et les aperçus affichent le modèle tel qu’écrit.

Un écran auquel il manque une valeur (un champ non défini, aucun emplacement), ou dont les valeurs forment une adresse de plus de 2048 caractères ou comportant un segment de chemin . ou .., ne reçoit pas cet iframe ou cette application, et les diagnostics de son manifeste portent screen_fact_missing ou screen_fact_invalid ; une page laissée vide est retirée. Chaque écriture qui atteint un tel écran (une écriture de liste de lecture, screen assign, screen update, une assignation de flotte, une revue approuvée) répond avec un avertissement screen_fact_missing qui nomme les jetons, les 20 premiers identifiants d’écran et leur nombre. Modifier un champ ou l’emplacement régénère le manifeste des écrans touchés.

Pour une application, chaque param rempli est ajouté à l’adresse de lancement après ticket, encodé en pourcentage, au plus 4096 caractères au total, de sorte que l’application le lit depuis location.search (SDK). Les params de lancement parviennent à l’application Web du Player et aux Players qui l’exécutent (Samsung Tizen, BrightSign, LG webOS et Vega) ; les Players Qt, Android, Apple et Windows chargent l’application depuis leur paquet local et n’en envoient aucun. Le champ url d’un modèle peut être un src d’iframe entier, et sa valeur peut elle-même porter des jetons d’écran, remplis à la construction du manifeste. Un sélecteur d’étiquettes utilise {screen.id} et {screen.field.NAME} de la même façon (ci-dessus). Les cartes gardent leurs propres jetons {screen.…}.

Disponibilité des médias

screenrig media availability med_ID --file rule.json définit quand les sélecteurs dynamiques (all, tag et folder) peuvent choisir un fichier. --clear supprime la règle et --expect-rev N protège la révision du média. L’API est PATCH /api/media/{id}/availability avec If-Match et { "availability": {...} | null }. Définir une règle exige l’accès Manage ; un identifiant Propose reçoit insufficient_access.

La règle reprend la grammaire horaire du calendrier, lue dans le fuseau horaire de chaque écran, et comporte au moins un membre : from et until (civil YYYY-MM-DDTHH:MM, until exclusif), windows (hebdomadaire {days, start, end}), monthly ({day} ou {nth, weekday}, chacun avec start et end facultatifs), dates ({date, start, end}) et except (dates qui retirent une occurrence, y compris les prolongements après minuit). Elle n’a ni data ni interaction. La création d’un commanditaire pour le long week-end, disponible uniquement les soirs de semaine dans cette période :

{
  "from": "2026-11-27T00:00",
  "until": "2026-11-30T23:59",
  "windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "17:00", "end": "22:00" }]
}

Seuls les sélecteurs lisent la règle : un sélecteur explicite id ou ids l’ignore, tout comme les références média des cartes, l’audio de la bande-son et les créations publicitaires. Un fichier quitte la sélection et y revient à la prochaine boucle de liste de lecture de chaque écran, dans la minute environ qui suit la limite. Aucune révision de liste de lecture ni de manifeste ne change, et un lecteur hors ligne garde sa dernière sélection jusqu’à sa reconnexion. screenrig media selector-preview --timezone ZONE (UTC par défaut) liste dans excluded les fichiers hors de leur règle à cet instant, avec le motif outside_window.

Retourner à la référence CLI de screenRIG.