Playlist: comandi CLI

Playlist

Una playlist è un documento JSON di pagine. playlist init prepara un documento a schermo intero da input ordinati. playlist create e playlist update leggono quel documento da un file; playlist patch, playlist rename e playlist page add|replace|remove ne modificano una parte. La forma è riassunta sotto i comandi.

playlist init <inputs...> --name NAME --output FILE [--overwrite] [--screen-id ID]
              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill] [--sound]
              [--no-transcode] [--no-progress] [--poll-ms MS]

screenrig playlist init med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --name "Lobby loop" --screen-id scr_01EXAMPLESCREEN00000000 --output lobby.json

playlist validate <file>

screenrig playlist validate ./lobby-loop.json

playlist create [file] [--from-template ID --name NAME [--set NAME=VALUE...] [--dry-run]] [--starter KEY [--name NAME]] [--format-region REGION --format-orientation ORIENTATION] [--note TEXT]

screenrig playlist create ./lobby-loop.json

screenrig playlist create --from-template pl_01EXAMPLETEMPLATE00000 --name "Monday notice" --set headline="Open late"

playlist update <id> <file> [--format-region REGION --format-orientation ORIENTATION] [--expect-rev REVISION] [--note TEXT]

screenrig playlist update pl_01EXAMPLEPLAYLIST000000 ./lobby-loop.json

playlist patch <id> [file] [--name NAME] [--clear-audio] [--expect-rev REVISION] [--note TEXT]

screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7
screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 changes.json --expect-rev 7

playlist rename <id> --name NAME [--expect-rev REVISION] [--note TEXT]

screenrig playlist rename pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7

playlist page add <playlist-id> (--file PAGE.json | --media MED_ID) [--seconds N] [--fit contain|cover] [--sound]
                  [--from WHEN] [--until WHEN] [--before PAGE_ID] [--page-id ID]
                  [--expect-rev REVISION] [--note TEXT]

screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEIMAGE0000000000 --from 2026-12-01 --until 2026-12-24
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEVIDEO0000000000 --before up-ab12cd34 --note "Winter menu"
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --file page.json --page-id welcome

playlist page replace <playlist-id> <page-id> [--file PAGE.json | --media MED_ID] [--seconds N] [--fit contain|cover]
                      [--sound] [--from WHEN] [--until WHEN | --always] [--expect-rev REVISION] [--note TEXT]

screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --media med_01EXAMPLEIMAGE0000000000
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --until 2026-12-31
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --always

playlist page remove <playlist-id> <page-id> [--expect-rev REVISION] [--note TEXT]

screenrig playlist page remove pl_01EXAMPLEPLAYLIST000000 up-ab12cd34

playlist show <id> [--output FILE [--overwrite]] [--editable]

screenrig playlist show pl_01EXAMPLEPLAYLIST000000
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --output playlist.json
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --editable

playlist list [--templates] [--library]

screenrig playlist list --templates
screenrig playlist list --library

playlist fields <id> [--set NAME=VALUE...] [--clear NAME...] [--refresh] [--expect-rev REVISION] [--note TEXT]

screenrig playlist fields pl_01EXAMPLECOPY00000000 --set headline="Closed today"

playlist instances <id>

screenrig playlist instances pl_01EXAMPLETEMPLATE00000

playlist revisions <id> [--after CURSOR]

screenrig playlist revisions pl_01EXAMPLEPLAYLIST000000

playlist revision show <id> --revision N

screenrig playlist revision show pl_01EXAMPLEPLAYLIST000000 --revision 3

playlist promote <id> --revision N --expect-rev CURRENT

screenrig playlist promote pl_01EXAMPLEPLAYLIST000000 --revision 3 --expect-rev 9

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

screenrig playlist delete pl_01EXAMPLEPLAYLIST000000

playlist export <id> --output DIRECTORY [--skip-applications]

screenrig playlist export pl_01EXAMPLEPLAYLIST000000 --output ./lobby-bundle

playlist import <directory> [--name NAME] [--update ID [--expect-rev REVISION]] [--poll-ms MS] [--note TEXT]

screenrig playlist import ./lobby-bundle
screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"
screenrig playlist import ./lobby-bundle --update pl_01EXAMPLEPLAYLIST000000

playlist replace-release <id> --page PAGE_ID --primitive PRIMITIVE_ID --release-id REL_ID
                         [--apply [--expect-rev REVISION] [--expect-impact TOKEN] [--note TEXT]]

screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW
screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW --apply

Il documento della playlist

Una playlist è name (da 1 a 120 caratteri) più pages (da 1 a 100), con una colonna sonora audio opzionale e un format opzionale. Ogni pagina porta id, canvas, transition, advance, visibility opzionale, audio_cue opzionale e primitives (da 1 a 24). Gli id di pagina, primitiva e traccia sono una lettera seguita da fino a 63 lettere, cifre, _ o -; gli id di pagina sono unici nella playlist e gli id di primitiva nella loro pagina. Un canvas prende width e height da 1 a 1.000.000, un background e un viewport_fit opzionale: vedi Sfondo e movimento della pagina.

Un format rende una playlist un video wall, {displays, arrangement, orientation} con columns per un grid, o una fascia, {region, orientation}. Un wall ha da 2 a 12 display da 1920 x 1080 (1080 x 1920 in verticale), ogni pagina ordinaria ha la tela del wall, e il displays di una primitiva indica le tessere che copre al posto di rect. Vedi Video wall e Fasce. Una pagina di slot pubblicitario, {id, type: "adslot", adslot_id} con visibility opzionale, non contiene tela né primitive; una playlist ne contiene al massimo 16 e mantiene una pagina ordinaria senza visibility.

Un modello aggiunge fields al documento, [{name, label, type, required, max_length?}] con type pari a text, media o url, e può contrassegnare qualsiasi primitiva come locked: true. Una pagina legge un campo come {field.NAME} nei params di una scheda (campi testo e indirizzo), come selector.media_id di un'immagine o di un video (un campo multimediale) o come src completo di un iframe (un campo indirizzo). Ogni segnaposto deve indicare un campo dichiarato del tipo giusto, ogni campo deve essere letto e una primitiva bloccata non ne legge alcuno; playlist validate lo verifica offline. Solo il proprietario o un membro che può approvare modifica una primitiva bloccata (primitive_locked). Un modello dichiara al massimo 16 campi: name è composto da 1 a 32 lettere minuscole, cifre o trattini bassi, label fino a 60 caratteri, e il max_length di un campo di testo (predefinito 200) fino a 2000. Un campo multimediale o indirizzo facoltativo lasciato senza valore esclude la primitiva che lo legge. Dichiarare fields e bloccare una primitiva fanno parte dei modelli di playlist, una funzionalità Premium. Un format di video wall da 2 o 3 schermi richiede Plus, uno da 4 a 12 schermi Enterprise. Un piano senza la funzionalità risponde feature_not_in_plan con required_plan, mentre una scrittura che mantiene ciò che la playlist ha già resta disponibile. Creare una copia da un modello è incluso in ogni piano.

Le sei primitive sono image, video caricato, stream dal vivo, iframe web e application, e card. Testo e cornice non sono tipi di trasmissione: inserisci una card per testo dal vivo, oppure carica un’immagine fissa finita creata dal tuo agente e inseriscila come immagine.

Uno stream prende una o due sorgenti ordinate con protocolli unici e un’immagine pronta dallo stesso progetto come fallback_media_id. Usa al massimo uno stream per pagina e avanzamento basato sulla durata. HLS usa un URL HTTPS pubblico; i Player Android e Qt si collegano direttamente ai flussi RTSP delle telecamere, credenziali incluse. Consulta i dettagli sui trasporti delle telecamere per i formati di URL aperti da ciascun Player; il multicast diretto UDP/MPEG-TS opzionale su Android e Qt usa un gruppo IPv4 in 239/8 e una porta. Una sorgente può indicare solo il suo url e lasciare che lo schema indichi il protocollo. Altri Player selezionano l’alternativa HLS o mostrano il fallback. I byte dello stream non sono memorizzati in cache per la riproduzione. L’audio è disattivato di default; muted impostato su false lo riproduce, con le regole per l’audio di un video descritte più avanti. L’import e l’export del bundle playlist non supportano gli stream.

{
  "id": "live",
  "primitive": "stream",
  "sources": [
    {
      "protocol": "udp-mpegts",
      "group": "239.10.0.1",
      "port": 5000
    },
    {
      "protocol": "hls",
      "url": "https://example.com/live.m3u8"
    }
  ],
  "fallback_media_id": "med_fallback",
  "muted": true,
  "rect": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "layer": 0,
  "content_fit": "contain"
}

Usa questa primitiva su una pagina con advance: {"mode":"duration","after_ms":30000}. Sostituisci il feed di esempio e l’ID di fallback. Requisiti del lettore e configurazione del trasporto.

Ogni primitiva è piatta: id, primitive, i campi propri di quella primitiva, poi rect, layer, content_fit, e enter e motion opzionali. Non esiste un oggetto contenuto annidato. rect è x, y, width e height in unità tela e layer un numero intero da 0 a 1024. Un rect può estendersi oltre la tela per l’abbondanza: i Player adattano il contenuto all’intero rect e poi ritagliano alla tela, quindi usa content_fit cover o fill per riempire la tela visibile. Una scheda si posiziona con layout e richiede un rect solo per free; su una playlist video wall displays sostituisce rect.

Le primitive immagine e video richiedono selector. selector.by è id con un media_id pronto e one_at_a_time false, ids con da 1 a 1,024 media_ids pronti univoci, all per ogni oggetto pronto di quella primitiva, tag che corrisponde a ^[A-Za-z0-9]{1,32}$, oppure folder con il folder_id di una cartella media mfd_ esistente, che riproduce i file pronti direttamente al suo interno e nessuna delle sue sottocartelle. Non mettere media_id sulla primitiva stessa e non inviare elementi risolti dal server. Una primitiva application fissa un release_id e una primitiva iframe richiede un src e un title da 1 a 200 caratteri, quindi nessuna delle due accetta un selettore. src è qualsiasi pagina http o https che lo schermo può raggiungere, inclusa una pagina LAN o dietro un login; un link YouTube viene memorizzato come il suo embed con riproduzione automatica. src, e il fallback_src facoltativo di un iframe, possono contenere token dello schermo come {screen.field.kiosk_id}, e una primitiva application può avere params con gli stessi token, così una playlist dà a ogni schermo la propria pagina. I Player Android, Amazon Signage Stick, Linux, Raspberry Pi e Windows aprono direttamente la pagina. L'app web Player e i Player macOS, Samsung Tizen, LG webOS e BrightSign la inseriscono in un frame, quindi una pagina che invia X-Frame-Options (DENY, SAMEORIGIN o l'obsoleto ALLOW-FROM), o un elenco Content-Security-Policy frame-ancestors senza l'origine del Player, mostra un frame bloccato su di essi, e l'app web Player mostra solo pagine https senza login nell'indirizzo. Quando la pubblicazione rileva una pagina HTTPS pubblica che rifiuta il framing, la scrittura riesce comunque e la CLI stampa la voce warnings del server: codice iframe_framing_refused, page_id, primitive_id e src, l'header che ha rifiutato e il passo successivo (usare una pagina che consente il framing dall'origine del Player, o chiedere al suo proprietario di consentire quell'origine). Il server aggiunge inoltre un'avvertenza playlist.iframe_framing_refused al registro eventi, una per pagina che rifiuta, che events list stampa con primitive_id. Una pagina LAN, una pagina http e una pagina che il server non raggiunge entro pochi secondi non vengono controllate. Un Player segnala una playlist come in riproduzione una volta che il suo manifest è a schermo, quindi una pubblicazione verificata non dimostra che una pagina iframe sia stata visualizzata: agisci sull'avvertenza, o guarda lo schermo. Entrambe le primitive web richiedono content_fit di fill, perché nessuna delle due ha una dimensione intrinseca.

Un iframe accetta anche reload_s (0, il valore predefinito, non ricarica mai; da 60 a 86400 ricarica src ogni reload_s secondi mentre la pagina è sullo schermo), fallback_src (la pagina mostrata quando src non si carica, con le forme e le regole di src; un src recuperato la sostituisce al ricaricamento successivo) e navigation_allowlist (da 1 a 64 origini host nella forma [scheme://]host[:port][path], come example.com, *.example.com o https://example.com/docs/; con un elenco, i link della pagina, le navigazioni via script e i reindirizzamenti raggiungono solo src, fallback_src e gli indirizzi corrispondenti; omettilo per nessuna restrizione, un elenco vuoto viene rifiutato). Un codice di incorporamento <iframe> incollato viene letto per il suo src. Una condivisione di Google Presentazioni, Documenti o Fogli, un link Pubblica sul web o di incorporamento, o un link Incorpora di Microsoft 365 viene memorizzato ricostruito per lo schermo: le presentazioni Google e PowerPoint si ripetono, una presentazione Google avanza secondo il ritardo proprio del link limitato alla durata della pagina (assegna alla pagina il tempo dell’intera presentazione), e Documenti, Fogli, Word ed Excel si ricaricano ogni 5 minuti. Un file che chiede agli spettatori di accedere viene rifiutato con document_not_shared, il cui dettaglio indica l’impostazione di condivisione da cambiare. Vedi Mostrare una pagina web, un video o un documento.

advance.mode è duration con after_ms, che su una pagina con esattamente un video YouTube (non una playlist né una diretta) può portare anche until impostato su video_end, così la pagina dura fino alla fine del video e after_ms è il tempo per cui viene mostrata quando lo schermo non riesce a leggere la durata del video, media_end su una pagina con esattamente un primitivo immagine o video, audio_end su una pagina il cui audio_cue nomina una traccia sonora, o application con max_ms quando l’app termina il proprio turno chiamando window.screenrig.nextPage(). Una pagina application necessita esattamente un primitivo marcato controller; ogni altra modalità lo vieta. after_ms, max_ms e dwell_ms sono millisecondi interi da 1.000 a 86.400.000, e un’immagine su una pagina media_end richiede dwell_ms. Una pagina contiene al massimo un stream e al massimo due primitivi application o iframe, e media_end vieta entrambi.

transition.type è uno tra crossfade, swipe-left, swipe-right, swipe-up, swipe-down, dip, wipe-left, wipe-right, wipe-up, wipe-down, slide-left, slide-right, slide-up, slide-down o stinger. duration_ms è obbligatorio, da 0 a 60000. playlist init scrive una dissolvenza incrociata di 200 ms. Lo swipe muove entrambe le pagine insieme come un carosello. Lo slide sposta la pagina in entrata sopra quella in uscita, che si sposta di un quarto della distanza. Il wipe scopre la pagina in entrata dietro un bordo netto in movimento. Il dip dissolve la pagina in uscita in un colore solido e poi nella pagina in entrata; color è un #RRGGBB opzionale, predefinito #000000, valido solo su dip. I nomi delle direzioni indicano la direzione del movimento: wipe-left è un bordo che si muove verso sinistra. ease è opzionale: linear, in, out o in-out; il predefinito è linear per crossfade e swipe-* e in-out per dip, wipe-* e slide-*; non è consentito su stinger. La pagina in entrata gestisce la propria transizione. La prima pagina di una playlist non ha transizione.

Uno stinger è una grafica a tema a schermo intero che copre la pagina in uscita, sostituisce la pagina in entrata mentre lo schermo è coperto, poi la scopre. Usalo per nominare una sezione di una playlist: mettilo sulla prima pagina della sezione. L’oggetto stinger è obbligatorio per type: "stinger" e non consentito per altri tipi. Tutti i suoi membri sono opzionali. theme è uno tra neomustard (default), cyanotype, propaganda, signal, avant-garde, bloom o primetime, e corrisponde ai temi delle schede. title è fino a 40 caratteri e subtitle fino a 60, impostati nel tipo di visualizzazione del tema. logo è media: più l’id di un’immagine pronta nel progetto, per esempio media:med_01EXAMPLE. accent è un #RRGGBB opzionale che sostituisce l’accento del tema. duration_ms per uno stinger è da 2000 a 6000 e copre tutto il bumper; le durate tipiche sono da 2700 a 4000. Il titolo resta completamente visibile per hang_ms, da 0 a 6000, default 1000 (un secondo), e hang_ms è al massimo il 60% di duration_ms; un hang più lungo richiede un duration_ms più lungo. Un Player che non può disegnare uno stinger riproduce un crossfade della stessa durata. Vedi la pagina live Stinger card per guardare la transizione in azione.

L’esempio seguente mostra una transizione di pagina con stinger:

{ "type": "stinger", "duration_ms": 3500, "stinger": { "theme": "primetime", "title": "BREAKFAST", "subtitle": "Served until 11", "logo": "media:med_01EXAMPLE", "hang_ms": 1000 } }

Un oggetto enter opzionale su una primitiva aggiunge un’animazione dell’oggetto: fade-up, fade-down, fade-left, fade-right, fade-in, zoom-in o zoom-out, e un stagger opzionale da 0 a 8 ritarda il suo inizio di 120 ms per passo. Un motion opzionale mantiene una primitiva in movimento dopo che è entrata: spin e drift ruotano o fanno scorrere un’immagine o un video, e path sposta un’immagine, un video, un’applicazione o un iframe lungo dei waypoint. Vedi Sfondo e movimento della pagina.

Un oggetto pagina visibility opzionale limita quando la pagina viene riprodotta: un booleano enabled obbligatorio, limiti civili from e until opzionali, e fino a 16 ricorrenze windows di giorni e orari civili. from e until sono YYYY-MM-DDTHH:MM nel fuso orario di ogni schermo, from incluso e until escluso e successivo a from; una finestra è days (da mon a sun) con start e end come HH:MM, indicati insieme o entrambi omessi per l’intera giornata, e un end uguale o precedente a start attraversa la mezzanotte. enabled: false nasconde la pagina; enabled: true richiede almeno uno tra from, until, windows o data. Ogni playlist mantiene almeno una pagina senza alcun campo visibility. Uno schermo legge questi orari nel suo fuso orario effettivo: il suo override, altrimenti la zona segnalata dal suo Player, altrimenti UTC.

Una condizione visibility.data di pagina, {key, path?, equals?}, mostra la pagina solo finché un documento dati della scheda corrisponde: key è una chiave dati della scheda o un ID scheda, path un puntatore RFC 6901 nel documento e equals una stringa, un numero, un booleano o null (omettilo per verificare che il valore esista). La chiave {screen.weather} legge il meteo della posizione propria di ogni schermo, che screen update ID --location LAT,LON imposta: {"enabled":true,"data":{"key":"{screen.weather}","path":"/condition","equals":"rain"}} mostra la pagina solo finché piove dove si trova quello schermo. Il documento meteo ha condition (clear, cloud, fog, rain, snow, storm o wind), band (freezing sotto 0 °C, cold da 0 a 9, mild da 10 a 17, warm da 18 a 24, hot da 25), temperatureC in gradi interi e isDay. È il meteo attuale della cella da 0,25 gradi dello schermo, aggiornato circa ogni ora, non una previsione. Uno schermo senza posizione non mostra mai la pagina, e la pubblicazione rifiuta un path o un equals che il documento non può contenere, come cloudy al posto di cloud. Un Player che non dichiara la capacità host page.conditions riceve una pagina del genere disabilitata. Le condizioni sui dati sono una funzionalità Plus: senza di essa, una scrittura che aggiunge una condizione visibility.data che la pagina non ha già riceve feature_not_in_plan, mentre mantenere o rimuovere una condizione salvata e la visibilità per fasce orarie restano disponibili. Mantieni una pagina ordinaria senza visibility come alternativa.

Una primitiva video o stream viene riprodotta senza audio a meno che non imposti muted su false. In tal caso riproduce il suo suono al volume dello schermo finché la sua pagina è quella corrente, e quella pagina mette in pausa la colonna sonora della playlist, che riprende dallo stesso punto nella pagina successiva senza suono. Più primitive su una stessa pagina riproducono tutte il proprio suono. Una pagina con suono non può avere un audio_cue: una scrittura che ne aggiunge uno risponde invalid_request in pages[i].audio_cue, «a page with sound cannot cue the soundtrack», mentre una pagina più vecchia già salvata che ha entrambi continua a essere riprodotta. Gli annunci restano senza audio.

Un oggetto audio opzionale di livello superiore aggiunge una colonna sonora che suona continuamente mentre le pagine cambiano e si mette in pausa su una pagina con audio. tracks elenca da 1 a 128 voci in ordine di riproduzione, ciascuna con un id unico (il pattern id pagina) e il media_id di un oggetto media audio pronto. loop predefinito è true e ricomincia dalla prima traccia dopo l’ultima; volume predefinito è 1 e varia da 0 a 1, moltiplicato per il volume del Player; cued predefinito è false, e true ferma la colonna sonora dopo ogni traccia così che una traccia suona solo quando una pagina audio_cue la avvia. Una pagina ordinaria può portare audio_cue con un id track da quella lista e un booleano restart opzionale (default false): quando la pagina appare, il Player passa a quella traccia dall’inizio, riavviandola solo se già in riproduzione e restart è true. I cue sono suggerimenti, le pagine adslot non possono portarli, e un cue senza colonna sonora è rifiutato. Una pagina con advance {"mode":"audio_end"} termina quando finisce la traccia che il suo audio_cue nomina, quindi richiede quel cue e una colonna sonora, non prende after_ms, e segue le regole duration per primitiva immagine e video; una primitiva stream necessita ancora di una pagina duration, e un’app sulla pagina non è mai il suo controller; max_ms è un suggerimento opzionale che il server sovrascrive. playlist update sostituisce l’intero documento, quindi omettere audio rimuove la colonna sonora; playlist patch la mantiene a meno che non sia fornito audio, e --clear-audio o audio: null la rimuove. Una fascia non ha colonna sonora. Composizione colonna sonora.