Schermi: comandi CLI

Associa un Player con il codice mostrato sul suo schermo.

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

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

La risposta contiene public_url e il valore screen associato. Il Player completa l’associazione la prossima volta che contatta il servizio, senza nulla da fare sul display: screen show riporta state active e online true quando l’ha fatto. Dopo una richiesta interrotta, riesegui lo stesso identico comando per riutilizzare la chiave di idempotenza salvata.

Completa la configurazione di un Player browser dal codice che mostra.

browser setup --code CODE [--open]

screenrig browser setup --code SETUP_CODE --open

La risposta contiene code, status (claimed), screen_id e player_public_url dello schermo. La CLI trattiene un URL che non supera i controlli di sicurezza, con l’avviso player_url_withheld. Un codice non valido o scaduto non crea alcuno schermo. Dopo una richiesta interrotta, riesegui lo stesso comando.

Elenca gli schermi. Gli schermi archiviati sono esclusi a meno che non vengano richiesti

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

I filtri si combinano. Ogni riga riporta tags, folder_id, fields e location dello schermo quando presenti. Con --human, la tabella aggiunge una colonna solo quando uno schermo elencato ha il valore: PLATFORM, REASON (archive_reason di uno schermo archiviato), TAGS, FOLDER, FIELDS, LOCATION, ASSIGNED (uno schermo che riproduce qualcosa di diverso dalla sua playlist predefinita), HEALTH (uno schermo che richiede attenzione) e UPGRADE (uno schermo il cui Player sta ancora passando alla versione della playlist emessa, o non ci è riuscito). --state archived elenca anche gli schermi che un Player ha archiviato da sé (device_reset, device_unpair) e gli schermi archiviati da screen replace (replaced).

Leggi uno schermo, inclusi revisione, assegnazione e stato online.

screen show <id>

screenrig screen show scr_01EXAMPLESCREEN00000000

tags elenca i tag della flotta dello schermo. effective_playlist, takeover e playlist_schedule riportano cosa riproduce lo schermo e perché; vedi Programmazioni e takeover. health e le capacità host del Player sono in Salute e alimentazione del dispositivo. online è vero mentre un Player è connesso, inclusa una breve finestra di riconnessione. last_online_at e last_ip opzionali appaiono dopo la prima connessione. observation opzionale riporta le superfici dipinte da un Player: id, width, height, pixel_ratio e presentation. Tutti questi sono di sola lettura; screen update non può inviarli, e uno schermo archiviato restituisce comunque la sua riga.

commands elenca gli ultimi 10 riavvii, ricaricamenti, svuotamenti della cache, riavvii dell'app e aggiornamenti dello schermo, dal più vecchio, ciascuno con il suo type, il suo state (queued, sent, done, failed, expired, cancelled o superseded), il suo source (schedule per un riavvio emesso da una programmazione dei riavvii; assente per uno richiesto da una persona), il suo expires_at e quando è stato inviato o completato. reboot_schedule e next_reboot_at riportano la programmazione dei riavvii dello schermo e l'inizio della sua prossima finestra di riavvio. Uno svuotamento della cache, un riavvio dell'app o un aggiornamento concluso dal Player contiene anche il suo cause e un breve detail, che --human stampa come colonna CAUSE e come riga sotto la tabella. suspension contiene message e since di uno schermo sospeso. Uno schermo archiviato da screen replace riporta replaced_by, lo schermo a cui è passato il suo dispositivo. Con --human, screen show li stampa tutti.

last_outage riporta l’ultima interruzione dello schermo: offline_since, back_at e duration_s e, quando un report di salute la determina, una likely_cause tra device_restart, app_crash, app_restart, network o platform; è assente quando screenRIG non riesce a determinarla. Un riavvio viene stabilito al ritorno dello schermo, mentre una causa di rete o di screenRIG attende il successivo report di salute del Player, che può richiedere fino a quindici minuti. glass contiene i verdetti che screenRIG ha tratto dai report di riproduzione e dagli screenshot dello schermo. Con --human, screen show stampa Last outage e Likely cause, e Playlist stalled, Blank screen o Frozen picture per un verdetto che ha trovato un problema; Notifiche dice cosa i verdetti lasciano fuori.

folder_id indica la cartella dello schermo ed è assente nella radice del progetto. fields, location e wall compaiono una volta impostati: vedi screen update e screen wall set. Ogni voce di observation.surfaces riporta anche rotation quando il Player può leggerlo, e un video wall riporta una voce per output, con i nomi che richiede screen wall set.

manifest_upgrade indica se il Player è passato alla versione della playlist emessa per lui. Il suo state è none, pending, downloading, preparing, activating, retrying, failed, blocked, partial o current, accanto a desired_playlist e active_playlist (id, name e revision), l’ultima versione che il Player ha confermato, il che non prova che ogni sessione la mostri. Un aggiornamento in errore o parziale riporta anche code, attempt, retry_at e missing_page_count. --human stampa Target v42 · Playing v41. Un aggiornamento fallito non pianifica alcun nuovo tentativo: correggi la causa, poi esegui screen reload oppure assegna di nuovo la playlist. Un’assegnazione salvata non conferma la riproduzione.

applications_unsupported compare finché il Player associato non può mostrare pagine application o iframe: il manifest resta invariato e il Player le salta. recovery_pending compare finché un display che ha perso la propria identità memorizzata si offre di riconnettersi come questo schermo, con expires_at dell’offerta e i valori platform, model, firmware e manufacturer che il display segnala: vedi screen recover.

Modifica in una sola chiamata il nome, l’assegnazione della playlist, l’override del fuso orario, i campi o la posizione di uno schermo.

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]

Indica almeno uno tra --name, --playlist-id, --clear-playlist, --timezone, --clear-timezone, --field, --unset-field, --clear-fields, --location o --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

In revisione, una modifica solo a --playlist-id è proposta come screen assign; una sessione Proponi non può modificare gli altri campi.

Modificare campi o posizione cambia la revisione del manifest dello schermo, quindi uno schermo che mostra una playlist recepisce i nuovi valori. Le card e le pagine iframe li leggono per schermo, quindi una sola playlist mostra i valori propri di ciascuno schermo: {screen.field.NAME}, {screen.name} e {screen.timezone} riempiono qualsiasi parametro di testo di una card, "location": "{screen.location}" riempie la posizione di una card nella forma che quella card accetta, e una chiave dati di una card può contenere {screen.field.NAME}, ad esempio menu-{screen.field.store_number}. Uno schermo che non ha un campo mostra quel testo vuoto, e la card rimane senza quella chiave dati o posizione. screen show elenca i campi e la posizione di uno schermo, e screen list trova gli schermi in base a essi. Vedi Token dello schermo negli indirizzi iframe e nei parametri dell’applicazione.

Crea una nuova playlist da un file preparato e assegnala a uno schermo.

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

Questo crea una nuova playlist e la assegna. Non aggiorna una playlist esistente per nome. Controlla prima il documento preparato. Ripeti l’input identico per riprendere un errore ambiguo. La lettura dell’assegnazione non prova la riproduzione; richiedi uno screenshot separatamente. In revisione restituisce stage: pending_review con entrambe le revisioni. Vedi Prepara, pubblica e modifica playlist.

Dopo l’assegnazione il comando attende finché il Player non mostra la playlist: data.stage è playing e data.playback_verified è true. I cambi di fase vengono stampati su stderr man mano che avvengono, come righe JSON o, con --human, come testo. Ripetere lo stesso identico comando dopo il termine di una pubblicazione riporta quella pubblicazione (data.already_published) finché lo schermo mostra ancora la sua playlist, e pubblica di nuovo quando lo schermo è passato ad altro.

Indirizza uno schermo, o una flotta di schermi, a una playlist.

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

Una playlist che programma pagine si assegna a qualsiasi schermo: le programmazioni sono lette nel fuso orario proprio dello schermo (il suo override, altrimenti la zona che il suo dispositivo riporta, altrimenti UTC).

Per pubblicare su una flotta, crea la playlist una volta con playlist create, poi esegui screen assign --tag TAG --playlist-id ID. screen publish punta a uno schermo.

Con l’accesso Propose, o in un progetto che richiede la revisione per le modifiche degli agent, la modifica a uno schermo o all’intera flotta risponde invece pending_review: data.review contiene l’ID della revisione e il relativo url nella dashboard, un avviso pending_review nomina l’url, e data.next è reviews show ID. Nulla cambia sullo schermo finché una persona non la approva, quindi non ripetere la scrittura. Su uno schermo in una cartella protetta questo risponde pending_review a ogni livello di accesso, e la decide un approvatore diverso da te e dalla persona per cui lavori (altrimenti second_approver_required, exit 3). Un chiamante limitato alle cartelle di schermi assegna solo su schermi del proprio ambito. Un’assegnazione salvata non conferma la riproduzione; screen screenshot mostra cosa c’è sullo schermo.

Imposta l’override del fuso orario in cui sono lette le regole civili di uno schermo, oppure rimuovilo.

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

Ogni schermo ha un fuso orario effettivo, e ogni regola civile lo legge: visibilità delle pagine, slot pubblicitari, programmazioni delle playlist, takeover, campagne, programmazioni dei display e dei riavvii, e {screen.timezone}. È questo override, altrimenti la zona che il Player dello schermo riporta dal suo dispositivo, altrimenti UTC. Uno schermo non necessita di override finché il suo dispositivo riporta la zona giusta. screen show stampa la zona effettiva come Timezone con la sua origine, effective_timezone e timezone_source (screen, device o default) in --json. Cambiare la zona effettiva rigenera la revisione del manifest.

ZONE è Area/City, come America/New_York o Asia/Tokyo, oppure UTC.

Imposta il video wall di uno schermo: un solo Player che pilota da due a dodici display come un unico canvas.

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 solo Player pilota i display come un unico video wall, quindi una pagina della playlist si estende su tutti. L’impostazione sostituisce l’intero video wall, quindi ripeti --rotation e --columns per mantenerli. Solo l’installazione kiosk del Player Linux e il Player Windows dichiarano la capacità display.wall; qualsiasi altro Player risponde wall_unsupported (exit 5) e nulla cambia. L’accesso Propose non può modificare un video wall (insufficient_access). Un wall da 2 o 3 schermi richiede Plus o superiore, uno da 4 a 12 schermi Enterprise: un piano senza risponde feature_not_in_plan (uscita 8), mentre screen wall clear e un’impostazione che mantiene il wall salvato restano disponibili. Vedi Video wall.

Crea la playlist per la forma del video wall con playlist init e l’ID dello schermo, che scrive il canvas corrispondente e format (displays, arrangement, orientation e columns per una griglia). L’elenco displays di una primitiva, ad esempio [2] o [1, 2, 5, 6], indica i numeri dei display che copre, contati da 1 da sinistra a destra e poi dall’alto verso il basso, e deve riempire un rettangolo del video wall. Assegnare una playlist il cui formato non corrisponde alla forma del video wall dà playlist_format_mismatch (exit 5); una playlist senza formato viene riprodotta allo stesso modo su ogni display. Quando lo schermo riproduce una playlist con un formato corrispondente, ogni display mostra il proprio numero e nome per 20 secondi dopo una modifica, così puoi verificare l’ordine sullo schermo.

Rimuovi il video wall di uno schermo.

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

screenrig screen wall clear scr_01EXAMPLESCREEN00000000

La playlist assegnata non viene ricontrollata: se ha un format, il manifest dello schermo passa a uno stato degradato (wall_format_mismatch) e il Player mantiene l’ultima pagina valida finché non assegni una playlist senza formato. Uno schermo senza video wall risponde senza modifiche. L’accesso Propose non può modificare un video wall (insufficient_access).

Nascondi uno schermo e scurisci il vetro.

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

screenrig screen archive scr_01EXAMPLESCREEN00000000

L’archiviazione nasconde lo schermo dall’elenco predefinito e scurisce il vetro. Non dissocia il lettore.

Chi possiede la chiave del display può comunque connettersi mentre lo schermo è archiviato. Per ritirare definitivamente l’hardware, lascia lo schermo archiviato, oppure sposta lo schermo su un nuovo hardware con screen recover o screen replace, che ritirano la vecchia chiave.

Ripristina uno schermo archiviato nella lista predefinita.

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

screenrig screen unarchive scr_01EXAMPLESCREEN00000000

Un Player può anche archiviare il proprio schermo: un reset confermato su un Player che detiene una chiave, o la dissociazione di un Player browser associato tramite cookie. screen show quindi segnala archive_reason come device_reset o device_unpair (project per un archivio richiesto), con archived_at. Lo schermo mantiene il suo vincolo dispositivo per ogni motivo, quindi un Player che ancora detiene quella chiave o cookie dispositivo resta spento e riprende su ripristino senza nuova associazione. Il Player che è stato resettato o dissociato perde la sua chiave o cookie e si associa di nuovo come nuovo schermo. Una chiave sostituita da un recupero schermo confermato resta ritirata.

Uno schermo archiviato come replaced da screen replace non mantiene alcun vincolo dispositivo, quindi il ripristino dall’archivio lo rifiuta e screen delete lo rimuove.

Mostra un avviso su uno schermo al posto dei suoi contenuti, finché non viene ripreso.

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

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

Uno schermo sospeso mostra il messaggio al posto dei suoi contenuti. Non cambia nient’altro: la sua playlist, la programmazione, il takeover e il controllo del display restano al loro posto e continuano a evolversi, e screen resume mostra ciò che lo schermo starebbe mostrando ora. screen show riporta suspension con message e since; sospendere uno schermo già sospeso sostituisce il messaggio e mantiene since. Sospendere aggiorna la revisione dello schermo, e il Player recupera subito i dati aggiornati. Uno schermo archiviato risponde screen_archived.

Termina la sospensione di uno schermo così che torni a mostrare i propri contenuti.

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

screenrig screen resume scr_01EXAMPLESCREEN00000000

Riprendere mostra di nuovo i contenuti propri dello schermo, a partire da ciò che lo schermo starebbe mostrando ora, e il Player recupera subito i dati aggiornati. Uno schermo non sospeso risponde invariato, senza cambio di revisione. Uno schermo archiviato risponde screen_archived.

Elimina uno schermo.

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

screenrig screen delete scr_01EXAMPLESCREEN00000000

Eliminare rimuove uno schermo solo finché nessuna chiave Player è associata ad esso, e screen show riporta deletable: true per quello schermo. Un Player che si associa tramite codice, nativo o browser, detiene una chiave, e la chiave resta associata al suo schermo: eliminare quello schermo risponde 409 screen_archive_required (codice di uscita 5); archiviarlo invece. Solo un Player browser associato tramite cookie non detiene alcuna chiave, e il suo schermo si elimina sia che sia associato sia che sia ancora in attesa.

Per associare come nuovo schermo un display che possiede una chiave, conferma un reset sul Player stesso, poi richiedi con screen pair il codice che mostra; il vecchio schermo resta archiviato. Per spostare uno schermo su hardware sostitutivo, usa screen recover, oppure screen replace quando quell’hardware è già associato come schermo a sé.

Ricollega un display che ha perso la propria identità memorizzata allo schermo con cui era stato associato.

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

screenrig screen show scr_01EXAMPLESCREEN00000000
screenrig screen recover scr_01EXAMPLESCREEN00000000

Un display che ha perso la propria identità memorizzata e ora segnala, durante l’associazione, gli identificatori hardware di questo schermo fa un’offerta. screen show la riporta come recovery_pending con la sua scadenza e, quando il display li segnala, platform, model, firmware e manufacturer. Nulla viene ricollegato finché questo comando non lo conferma: lo schermo mantiene etichetta, playlist, fuso orario, programmazioni e cronologia, e la nuova chiave del display sostituisce la precedente, che decade dopo una finestra di grazia di quindici minuti. Uno schermo archiviato da un reset del dispositivo resta archiviato finché non viene eseguito screen unarchive.

Prima di confermare, confronta il modello e il firmware segnalati con il display che ti aspetti: qualsiasi applicazione in esecuzione su un display può leggerne gli identificatori, quindi la sola offerta non prova da quale display proviene. Il servizio rifiuta un’offerta finché il Player attuale dello schermo è ancora online, e uno schermo accetta al massimo tre offerte all’ora. Senza un’offerta il comando risponde recovery_not_offered, un’offerta la cui sessione di associazione è scaduta risponde recovery_expired, e identificatori collegati a più di uno schermo rispondono recovery_ambiguous; nulla viene ricollegato. Il recupero non attraversa mai i progetti.

Sposta su questo schermo il dispositivo associato come un altro schermo, mantenendo le impostazioni e la cronologia di questo schermo.

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

screenrig screen replace scr_01EXAMPLESCREEN00000000 --with scr_01EXAMPLENEWSCREEN000000

Associa prima il nuovo hardware come schermo a sé stante, poi sostituisci. La chiave del dispositivo, o la credenziale di un Player browser, ora apre <id>, che mantiene nome, tag, fuso orario, playlist, programmazioni, takeover, programmazione display e override, video wall, commenti, campi, posizione e cronologia, e prende l’host e il Player dello schermo sostitutivo. Salute, stato, spazio di archiviazione e comandi in coda ricominciano da zero. Lo schermo indicato da --with viene archiviato con archive_reason replaced e replaced_by che indica <id>. Non mantiene alcun vincolo dispositivo, quindi screen unarchive non può ripristinarlo e screen delete lo rimuove. La chiave che <id> deteneva viene ritirata dopo una finestra di grazia di quindici minuti, poi il suo vecchio dispositivo viene rifiutato. Entrambi gli schermi devono essere attivi con un Player associato: uno schermo ancora in attesa di associazione risponde resource_conflict, uno archiviato risponde screen_archived, e un video wall richiede un Player sostitutivo che dichiara display.wall (wall_unsupported). La richiesta porta sempre una chiave di idempotenza, e un retry esatto restituisce la risposta originale.

Per ricollegare un display che ha perso la propria identità memorizzata e ora segnala gli identificatori di questo schermo, usa screen recover.

Emettere un nuovo ID pubblico per uno schermo.

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

screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

Il valore public_id dello schermo, la credenziale nel suo URL pubblico, viene sostituito e ogni sessione aperta con il precedente termina. L’associazione del Player resta: un Player associato apre una nuova sessione e continua a mostrare i suoi contenuti.

Crea il link di uno schermo, o sostituiscilo, e stampa il suo URL Player.

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

screenrig screen link create scr_01EXAMPLESCREEN00000000

Stampa data.url, l’URL Player (https://play.screenrig.ai/player/#screen=…) da incollare come URL di una sorgente browser in vMix o OBS, che non conserva dati e altrimenti perderebbe l’associazione a ogni caricamento. Il Player funziona dall’URL a ogni caricamento: l’URL è l’intera associazione. Creare di nuovo il link lo sostituisce (data.replaced è true): il vecchio URL smette subito di funzionare e il Player aperto da esso mostra un avviso senza contenuto. L’URL è una credenziale che apre lo schermo: viene stampato sotto un’etichetta sensibile, tenuto fuori dal log delle operazioni e mostrato di nuovo da screen link show. Aprilo in un solo posto. Uno schermo non ancora associato risponde resource_conflict (exit code 5), e uno schermo archiviato risponde screen_archived. Dopo una richiesta interrotta, riesegui lo stesso comando: riutilizza la chiave di idempotenza salvata e restituisce lo stesso link.

Stampa il link di uno schermo e il suo URL Player.

screen link show <id>

screenrig screen link show scr_01EXAMPLESCREEN00000000

Stampa data.url sotto un’etichetta sensibile con data.hint (gli ultimi quattro caratteri del segreto), data.created_at e data.last_used_at una volta che un Player ha aperto il link. Una credenziale di sola lettura riceve url vuoto con url_redacted true, e l’output umano dice che l’URL è trattenuto; un accesso Manage lo riceve. Uno schermo senza link risponde screen_link_not_found (exit code 4) e indica il comando che ne crea uno. screen show stampa Screen link: on (…HINT) per uno schermo che ne ha uno, e mai il suo URL.

Disattiva il link di uno schermo.

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

screenrig screen link delete scr_01EXAMPLESCREEN00000000

L’URL smette subito di funzionare e ogni sessione che ha aperto termina: una sorgente browser che lo mostra ancora visualizza un avviso e nessun contenuto finché non riceve un nuovo URL. Lo schermo, la sua associazione e i suoi contenuti restano intatti. Riesce, senza cambiare nulla, quando lo schermo non ha un link.

Chiedi al lettore di uno schermo, o a tutti i lettori di una flotta, di ricaricare una volta.

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 risposta include un reload_id, un state e un expires_at. Uno schermo online riceve subito la ricarica (state sent); uno schermo offline la mantiene in stato queued e la riceve quando torna online prima di expires_at, 24 ore dopo la richiesta salvo diversa indicazione in --expires-in. Una ricarica più recente sostituisce quella ancora in coda, screen show elenca i commands dello schermo e screen command cancel annulla una ricarica ancora in coda. In una flotta, il reload di ogni risultato contiene lo stesso state. Un Player web si ricarica al prossimo cambio pagina; un Player nativo si ricollega, recupera il manifesto e verifica aggiornamenti. Un Player ignora una ricarica entro dieci minuti dall’ultima eseguita. La ricarica funziona su schermi attivi e archiviati e non cambia la revisione dello schermo.

Invia un messaggio transitorio come stage chrome su uno schermo live o una flotta.

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 non è un primitivo: non occupa slot canvas, non ha layer e non partecipa a readiness o crossfade. Vince l’ultimo, non c’è coda né annulla, e l’involucro accettato è solo { expires_at }. Non mettere mai credenziali o altri materiali segreti nel testo.

Mostra il nome di uno schermo sopra i suoi contenuti per un po’, così da trovarlo in loco.

screen identify <id> [--duration DURATION]

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

Il Player disegna una sovrapposizione a schermo intero sopra i propri contenuti, con il nome dello schermo molto grande e il suo ID in piccolo sotto. La riproduzione continua al di sotto, e un’identificazione più recente sostituisce la sovrapposizione. La busta accettata contiene identify_id, duration_ms e un expires_at 60 secondi dopo la richiesta, così uno schermo offline non la mostra mai in seguito. Solo un Player che dichiara la capacità identify mostra la sovrapposizione: qualsiasi altro schermo risponde 409 identify_unsupported (codice di uscita 5) e non viene inviato nulla, quindi aggiorna il Player o mostra il nome con screen toast. Uno schermo archiviato risponde screen_archived e uno schermo ancora in attesa di associazione risponde resource_conflict. Identificare non cambia la revisione dello schermo.

Avvia una pagina della playlist che uno schermo sta riproducendo ora, per verificarla con uno screenshot.

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

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

La pagina riparte dall’inizio sul Player dello schermo e la rotazione prosegue da lì, quindi uno screenshot fatto subito dopo mostra quella pagina senza attendere la fine della rotazione. La pagina deve appartenere alla playlist che lo schermo riproduce ora: il suo takeover, altrimenti una campagna che lo detiene, altrimenti la sua programmazione, altrimenti la playlist assegnata. Qualsiasi altra pagina risponde page_not_on_screen (exit 5), e il problema nomina quella playlist. Un Player che non dichiara la capacità play_page nel proprio report host risponde play_page_unsupported (exit 5) e non viene inviato nulla: aggiorna il Player.

La risposta contiene playlist_id, page_id, manifest_revision e expires_at. La richiesta scade dopo 60 secondi e non modifica la revisione dello schermo. Uno schermo archiviato risponde screen_archived e uno schermo ancora in attesa di associazione risponde resource_conflict. Un nuovo tentativo con la stessa chiave di idempotenza riproduce la risposta originale.

Cattura un fermo immagine di uno schermo attivo, o di ogni schermo in una flotta, e scrivilo su disco.

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

Il comando resta in attesa finché il WebP non è su disco. La busta riporta screen_id, capture_id, path, bytes, sha256, width e height, e mai i byte dell’immagine. Vince l’ultima richiesta: una richiesta successiva sostituisce un’acquisizione in corso. Uno screenshot dell’app web del Player disegna ogni pagina iframe come un riquadro grigio scuro con l’etichetta "Embedded web page" e ogni applicazione come la rende l’applicazione stessa; l’immagine non contiene alcun indicatore del riquadro, quindi non prova che una pagina iframe sia stata visualizzata.

Con più ID, --tag o --folder, la risposta è un risultato di flotta con action: "screenshot", il selector e la directory output; ogni risultato ok riporta path, bytes, sha256, width e height. Con --tag, la CLI elenca prima gli schermi con tag, seguendo ogni pagina dell’elenco; ogni pagina dell’elenco è una richiesta agente e le acquisizioni stesse non sono contate, e più ID non richiedono un elenco. --idempotency-key è rifiutato in questa forma, perché ogni acquisizione usa la propria chiave. Se un’acquisizione fallisce in modo imprevisto, il risultato di quello schermo è unexpected_error, non partono nuove acquisizioni, gli schermi ancora in attesa riportano not_attempted e il codice di uscita è 1.

Per un solo schermo la busta contiene anche frame.flat, che indica se questa immagine è di un solo tono uniforme, e picture, il verdetto dello schermo su vuoto o bloccato quando ne ha uno. Un’immagine uniforme da sola non è un verdetto: una transizione tra pagine, o una pagina nera di proposito, appare uguale. Con --folder, la CLI elenca la cartella e ogni cartella al suo interno, con un’esecuzione di screen list --folder per cartella, e uno schermo che l’elenco mostra offline viene segnalato come fallito senza acquisizione.

Il server ammette 10 acquisizioni per schermo, 30 per organizzazione e 30 per indirizzo al minuto; la CLI ritenta le risposte 429 e 5xx con backoff e rispetta Retry-After. Un’acquisizione che non può essere completata è screenshot_unavailable (exit 5): lo schermo è offline, la richiesta ha dato timed_out, la pagina mostrata contiene una superficie che il Player non può acquisire (unsupported_surface, ad esempio un iframe di terze parti visibile nel Player del browser), l’acquisizione del Player è fallita (capture_failed), oppure l’acquisizione era ancora in sospeso quando il tempo di --timeout si è esaurito. --timeout 0 lascia l’attesa al server, che fa scadere una richiesta senza risposta dopo 30 secondi. Un’acquisizione fallita contiene error.display quando il Player ha segnalato il proprio display: power, connected, reported_at e stale (dopo 35 minuti). Un report off o standby recente suggerisce di riprovare quando il display è acceso.

Avvia la vista live di uno schermo, o rinnovala, e stampa la pagina della dashboard che la mostra.

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 vista live mostra come video nella dashboard ciò che uno schermo riproduce; la CLI avvia, legge e termina la sessione e non trasporta mai il video. data è la sessione con viewer_url, la pagina da aprire. Avviare uno schermo che ha già una sessione la rinnova: il lease si estende fino alla più tarda tra la sua fine attuale e --duration da adesso, mai oltre cinque minuti dopo l’inizio della sessione. Poi la sessione termina da sola: nulla la rinnova né la riavvia, e la sessione successiva richiede un nuovo screen live start. Termina prima quando il lease scade, con screen live stop, o quando la termina il Player.

Il comando chiede al Player di pubblicare e legge la sessione ogni secondo per --wait finché il Player non segnala di essere connesso. Se il Player non si è connesso allo scadere dell’attesa, la risposta è comunque ok con l’avviso live_not_ready: leggi di nuovo screen live status, oppure apri viewer_url. Una sessione terminata durante l’attesa è live_unavailable (exit 5) e il suo dettaglio nomina ended_reason, ad esempio consent_timeout (su Android, una persona davanti allo schermo consente l’acquisizione dello schermo una volta a ogni avvio del Player). Anche uno schermo offline è live_unavailable, e uno archiviato risponde screen_archived. Un Player che non dichiara la capacità live_view risponde live_unsupported (exit 5) e non viene inviato nulla: aggiorna il Player. Un server senza relay multimediale risponde feature_unavailable: usa screen screenshot. La vista live è gratuita. Vedi Vista live.

Leggi la sessione di vista live di uno schermo.

screen live status <id>

screenrig screen live status scr_01EXAMPLESCREEN00000000

state è idle (nessuna sessione), requested (al Player è stato chiesto), publishing (il relay ne ha il video) o ended, con ended_reason per dieci minuti. publisher.connected è la segnalazione del Player stesso, risalente a non più di 45 secondi fa, e non prova che ci sia un’immagine. data include viewer_url.

Termina la sessione di vista live di uno schermo.

screen live stop <id>

screenrig screen live stop scr_01EXAMPLESCREEN00000000

Termina la sessione e dice al Player di smettere di pubblicare, poi stampa la sessione così com’è: ended con ended_reason stopped. Riesce anche quando non esiste alcuna sessione. Una sessione termina anche da sola quando il suo lease scade.

Salva fotogrammi JPEG di ciò che uno schermo riproduce, dal suo stream live, per verificare riproduzione e movimento.

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

Il comando avvia la sessione live, attende che il Player pubblichi, chiede i fotogrammi al relay multimediale e legge ogni nuovo fotogramma una sola volta. Un fotogramma è il video così come l’ha inviato l’encoder del Player, ridimensionato a un massimo di 1280x720 e con perdita di qualità, circa uno al secondo: mostra il movimento e ciò che è sullo schermo adesso, quindi confronta i fotogrammi (--count 5 --interval 1s) per verificare che il contenuto si muova. Non è uno screenshot, che resta la prova del layout. I fotogrammi sono gratuiti.

data è {screen_id, live_id, frames}, con path, captured_at, width, height, bytes e sha256 per fotogramma, e stopped true quando --stop ha terminato la sessione. Senza --stop la sessione viene lasciata al suo lease. Un Player che non pubblica entro --wait, o che non invia nessun nuovo fotogramma entro tale tempo, è live_not_ready (exit 5); su Android, una persona davanti allo schermo consente l’acquisizione dello schermo una volta a ogni avvio del Player. Una sessione terminata, o i cui fotogrammi hanno smesso di arrivare, è live_unavailable (exit 5). Un Player senza la capacità live_view risponde live_unsupported, e un server senza relay multimediale o fotogrammi risponde feature_unavailable (exit 4): usa screen screenshot.

Imposta, aggiungi, rimuovi o cancella i tag su uno schermo o una flotta.

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

Un tag è da 1 a 32 lettere o cifre, e uno schermo porta al massimo 16 tag unici. I tag selezionano flotte; non sono mai autorizzazione e non raggiungono mai il Player. Cambiare i tag aggiorna la revisione dello schermo, non quella del manifesto. Per uno schermo l’involucro è lo schermo aggiornato. --add e --remove leggono prima lo schermo e scrivono il nuovo set protetto da --expect-rev o dalla revisione appena letta, così un cambiamento concorrente restituisce revision_conflict (exit 6) invece di essere sovrascritto; rilancia il comando. In una flotta, --add e --remove si applicano atomicamente contro il set memorizzato di ogni schermo, e uno schermo che supererebbe 16 tag fallisce nel proprio risultato con invalid_request.

Ovunque i tag cambino (screen tag, un aggiornamento dello schermo tramite l'API, l'editor di tag della dashboard), il levels della risposta elenca, sotto gained e lost, le campagne il cui pubblico di tag lo schermo ha raggiunto o lasciato, ciascuna con il suo source (campaign), il suo id, il conteggio di screens e, quando la campagna ha una copertura, reach_before e reach_after. Un screen tag di flotta li somma sulla flotta. Leggi levels.lost prima di considerare innocua una modifica di tag: rimuovere l'ultimo tag corrispondente dagli schermi di una campagna svuota quel gruppo e fa scattare le notifiche reach_dropped e group_empty.

Sposta schermi e cartelle di schermi in una cartella di schermi, o di nuovo nella radice del progetto.

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

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

Lo spostamento è un’unica richiesta tutto o niente. Una cartella si sposta con tutto il suo contenuto e non può essere spostata in se stessa né in una cartella al suo interno; le cartelle si annidano fino a 10 livelli. Gli elementi già presenti nella destinazione restano come sono e non vengono contati. data.screens e data.folders contano ciò che è stato spostato. data.levels elenca, sotto gained e lost, le campagne il cui pubblico di cartella gli schermi spostati hanno raggiunto o lasciato (source campaign, con reach_before e reach_after) e le playlist predefinite di cartella che hanno iniziato o smesso di mostrare (source folder). Gli schermi risolvono di nuovo la loro playlist entro circa 15 secondi; screen show riporta effective_playlist, e campaign explain SCREEN_ID ne spiega il motivo.

Un chiamante limitato alle cartelle di schermi sposta solo schermi e cartelle del proprio ambito in una cartella dello stesso ambito; qualsiasi altra cosa, radice del progetto compresa, fa rifiutare l’intero spostamento con outside_screen_scope (exit 3). Uno spostamento dentro o fuori da una cartella protetta risponde pending_review con una revisione protected_change che decide un secondo approvatore, quindi non ripetere la scrittura; --note spiega all’approvatore il motivo. Dopo una richiesta interrotta, riesegui lo stesso identico comando per riutilizzare la chiave di idempotenza salvata.

Elenca le cartelle di schermi del progetto come albero, con gli schermi attivi direttamente contenuti in ciascuna e la sua playlist predefinita.

screen folder list

screenrig screen folder list

Restituisce ogni cartella di schermi del progetto, al massimo 1000, ordinate per nome. data.items contiene per ogni cartella id, name, parent_id (null nella radice del progetto), default_playlist_id se impostato, protected se impostato, screens (gli schermi attivi direttamente al suo interno, non quelli delle cartelle sottostanti) e revision. Con --human, l’output è l’albero, una riga per cartella con il suo percorso. La cartella di uno schermo è folder_id in screen list e screen show, assente nella radice del progetto. Basta l’accesso di sola lettura.

Ispeziona una cartella di schermi.

screen folder show <id>

screenrig screen folder show sfd_01EXAMPLEFOLDER000000000

Restituisce una cartella con i campi che restituisce screen folder list. Basta l’accesso di sola lettura.

Crea una cartella di schermi nella radice del progetto o all’interno di un’altra cartella.

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

Un’organizzazione contiene al massimo 1000 cartelle in tutti i suoi progetti (quota_exceeded), annidate fino a 10 livelli (invalid_request). Inserisci gli schermi con screen move. Una cartella indica poi i suoi schermi nei comandi per la flotta e come pubblico di una campagna: vedi Cartelle di schermi.

Un chiamante limitato alle cartelle di schermi crea cartelle solo all’interno del proprio ambito: --parent deve essere una sua cartella (outside_screen_scope, exit 3). Una cartella creata in una cartella protetta risponde pending_review con una revisione protected_change che decide un approvatore diverso da te e dalla persona per cui lavori, quindi non ripetere la scrittura; --note spiega all’approvatore il motivo. Dopo una richiesta interrotta, riesegui lo stesso identico comando per riutilizzare la chiave di idempotenza salvata.

Rinomina una cartella di schermi, spostala con tutto il suo contenuto, oppure imposta o cancella la sua playlist predefinita.

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]

Indica almeno uno tra --name, --parent, --root, --default-playlist-id, --clear-default o --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"

Una cartella non può essere spostata in se stessa né in una cartella al suo interno, e gli stessi valori non hanno alcun effetto. Uno spostamento o una modifica del valore predefinito risolve di nuovo gli schermi al suo interno entro circa 15 secondi, e data.levels elenca le campagne il cui pubblico di cartella quegli schermi hanno raggiunto o lasciato (source campaign) e le playlist predefinite di cartella che hanno ottenuto o perso (source folder).

Una rinomina ha effetto immediato su una cartella protetta. Uno spostamento, o una playlist predefinita, di una cartella che è protetta o ne contiene una risponde pending_review con una revisione protected_change che decide un secondo approvatore (un approvatore diverso da te e dalla persona per cui lavori; altrimenti second_approver_required, exit 3). Fino ad allora nulla cambia, quindi non ripetere la scrittura; --note spiega all’approvatore il motivo. Una persona che può approvare protegge una cartella nella dashboard; la CLI propone soltanto di rimuovere la protezione con --unprotect. Vedi Cartelle protette. Un chiamante limitato alle cartelle di schermi modifica solo cartelle del proprio ambito e le sposta solo in una cartella superiore dello stesso ambito (outside_screen_scope, exit 3), e mai la protezione di una cartella nominata dal suo ambito.

Elimina una cartella di schermi; i suoi schermi e le sue cartelle salgono di un livello.

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

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

Elimina solo la cartella: i suoi schermi e le sue cartelle salgono nella cartella superiore (la radice del progetto se non ne ha una) e quegli schermi risolvono di nuovo la loro playlist. data è id, deleted true e levels, le campagne e le playlist predefinite di cartella che gli schermi spostati hanno ottenuto o perso, con reach_before e reach_after di ciascuna campagna. Un pubblico di campagna che nomina la cartella rifiuta l’eliminazione con resource_conflict (exit 5): modifica o elimina prima quelle campagne.

Un chiamante limitato alle cartelle di schermi elimina solo cartelle all’interno del proprio ambito, mai una cartella nominata dal suo ambito (outside_screen_scope, exit 3). Una cartella che è protetta o ne contiene una risponde pending_review con una revisione protected_change che decide un secondo approvatore, quindi non ripetere la scrittura; --note spiega all’approvatore il motivo.