Scegli il giusto percorso di creazione

Guarda come viene costruito

Film / Crea un’app kiosk con l’SDK

3:07

Usa screenrig dopo la configurazione della sessione su Avvia.

Scegli il percorso dei contenuti

La generazione imposta insieme grafica e testo, quindi inserisci tutto il testo nel prompt. Le card disegnano il proprio testo nel Player, quindi una parola o un numero modificato non richiede una nuova immagine statica. Le risorse finite fornite non richiedono generazione. L’animazione da sola non richiede nessuna delle due.

Genera un’immagine statica completa

L’agente invia un prompt più aspect_ratio e quality. screenRIG restituisce un oggetto media med_… nel negozio media dell’account. Il chiamante non ricarica i byte. Recupera i byte originali solo per ispezionare; altrimenti conserva il riferimento med_… in una playlist.

Il proprio media upload rimane valido. Non generare se si possiede già il file. Video live, stream, iframe e pagine app web sono primitive di playlist, non immagini generate.

La qualità è low, medium, o high (default medium). Il rapporto d'aspetto è 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, o 2:3 (default 16:9). --quality cambia il livello di dettaglio dell'immagine fissa e quindi quanti token usa:

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

La busta riporta un id med_…. Non stampa mai i byte dell’immagine.

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

Aggiungi una colonna sonora

Una playlist può avere una colonna sonora: una lista ordinata di tracce MP3 che suona continuamente mentre cambiano le pagine. Le transizioni di pagina non fermano, riavviano o sfumano la musica. La colonna sonora è un’impostazione della playlist, non una settima primitiva, quindi non ha rettangolo o livello sulla tela.

Carica ogni traccia con media upload. I file MP3 vengono caricati così come sono; WAV, AAC, M4A, OGG e FLAC vengono prima convertiti in MP3. Ogni traccia diventa un oggetto media audio con un id med_… e una durata.

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

Nomina le tracce nella playlist audio membro; contiene da 1 a 128 tracce. Le tracce suonano in ordine, una dopo l’altra. loop (default true) ricomincia dalla prima traccia dopo l’ultima; volume (default 1, da 0 a 1) scala il volume proprio del 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" }
  ]
}

Una pagina può avere un audio_cue opzionale. Quando quella pagina appare, il Player passa alla traccia nominata dall’inizio; se quella traccia è già in riproduzione, si riavvia solo se restart è true. La sequenza continua quindi dalla traccia indicata. Le cue sono suggerimenti: un Player le applica con un breve fade o le salta se la traccia non è pronta. Le pagine senza cue lasciano la musica intatta. I campi della pagina diversi da id e audio_cue sono omessi nell’esempio sopra.

Sostituire una playlist sostituisce anche la sua colonna sonora; escludi audio per rimuoverla. I video sulla tela restano muti, quindi la colonna sonora è l’unico suono riprodotto da uno schermo.

Associare una pagina a una traccia

Per un album o un libro con una pagina per traccia, o qualsiasi pagina che dura esattamente quanto una traccia, associa la pagina alla sua traccia.

Imposta la pagina advance su { "mode": "audio_end" }. La pagina applica il suo audio_cue quando appare, come fa qualsiasi segnale, e termina quando quella traccia finisce, come una pagina media_end termina con il suo video. La pagina deve avere un audio_cue e la playlist una colonna sonora audio. Le primitive immagine e video seguono le regole duration: niente dwell_ms, e one_at_a_time: true su ogni selettore dinamico (all, tag, folder o ids con più di un id), anche se corrisponde a un oggetto oggi. Una primitiva stream necessita ancora di una pagina duration, e un’applicazione sulla pagina non è mai il suo controller. max_ms è un suggerimento di sicurezza opzionale; il server imposta la scadenza dalla durata della traccia, quindi ometterlo. Se il Player non può riprodurre la traccia, la pagina dura comunque la lunghezza della traccia.

Imposta cued su true nel membro audio per fermare la colonna sonora dopo ogni traccia. Una traccia in coda si riproduce solo quando una pagina audio_cue la avvia. Continua a suonare sotto qualsiasi pagina ordinaria che segue la sua pagina fino alla fine, poi la colonna sonora è silenziosa fino alla prossima coda, così pagina e traccia restano legate, con qualsiasi numero di pagine ordinarie tra pagine legate. loop non ha effetto su una colonna sonora in coda, e cued predefinito è 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 } }
  ]
}

I campi pagina diversi da id, advance e audio_cue sono omessi dall’esempio sopra.

Posiziona una card per testo live

Una card integrata disegna testo, un menù, una tabella, un orologio o un indicatore direttamente nel Player, così il testo resta modificabile e un nuovo valore raggiunge ogni schermo senza una nuova immagine statica. cards list mostra i tipi, card create crea un’istanza e la playlist la posiziona come primitiva card. card data put scrive i suoi valori live. Card elenca ogni tipo e layout.

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

Mostrare una dashboard dietro un accesso

Una connessione web accede a un sito come farebbe una persona, con un account di servizio, e una vista web mostra una pagina di quel sito. Va bene per le dashboard di Salesforce, Looker Studio, Datadog, HubSpot e di qualsiasi altro sito senza link pubblico. Un browser sul bordo di screenRIG apre la pagina già connesso e il Player ne mostra un’immagine, ridisegnata ogni refresh_s secondi (da 60 a 86.400, 300 per impostazione predefinita). Tutti gli schermi della stessa dimensione condividono un’immagine, quindi più schermi non aggiungono accessi, e un’immagine viene disegnata solo mentre la playlist di uno schermo mostra la vista. Le connessioni e le viste Grafana, Power BI e Tableau funzionano allo stesso modo e sono nel riferimento API.

1. Crea un account di servizio sul sito che possa leggere solo le dashboard che i tuoi schermi mostrano. Ogni acquisizione accede come lui.
2. Crea la connessione con kind web e le impostazioni qui sotto. La password è secret.
3. Crea una vista di una pagina: il suo indirizzo https come url e, come wait_for, un selettore CSS di un elemento che compare solo quando la pagina è connessa e pronta, così una pagina di accesso scade invece di essere disegnata. clip disegna solo la parte della pagina che un selettore indica, e wait_ms (fino a 10.000) attende i grafici tardivi.
4. Colloca il embed_url della vista in una primitiva iframe con 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"
}

La password, la chiave TOTP e i cookie stanno accanto a config, sono memorizzati sigillati e non vengono mai più mostrati: una lettura dice se ciascuno è impostato. Un secret o totp_secret vuoto, o cookies: [], lo rimuove.

• Prima i cookie. La connessione tiene un solo set di cookie sigillato: quello che hai incollato, poi i cookie che ogni acquisizione restituisce. Un’acquisizione invia il set di cookie e nessuna credenziale, e accede solo quando non c’è un set o l’ultima acquisizione ha raggiunto una pagina di accesso. Un sito che tiene la sessione fuori dai cookie accede a ogni acquisizione, quindi dai alla sua vista un refresh_s lungo.
• La password va solo alla pagina di accesso. Viene digitata in login_url e nei passaggi goto, mai nell’indirizzo di una vista. Aggiungere un indirizzo all’uno o all’altro richiede la password nella stessa richiesta, quindi un membro che non può leggere la password non può indirizzarla a una pagina propria.
• L’account è protetto. Un accesso rifiutato (bi_web_login_failed o bi_web_otp_required) attende 5 minuti, poi 15, 60 e 120, e il quinto di fila ferma la connessione finché non cambi le sue credenziali o le sue impostazioni di accesso, quindi nella prima ora vengono eseguiti al massimo 3 tentativi. Un accesso che termina in altro modo (timeout, blocco, pagina che non si è aperta) attende 15 minuti. Usa un account di servizio in sola lettura.
• Alcuni siti non si possono automatizzare. Un sito che approva gli accessi su un telefono, controlla i dispositivi o mostra un CAPTCHA richiede un set di cookie (login_mode none) o un account di servizio che il sito esenta.

Il Player conserva l’ultima buona immagine mentre un’acquisizione fallisce, e lo stato della vista riporta uno di questi codici:

screenrig bi connection test ID accede e riporta il risultato. Il session di una connessione dice a che punto sono i suoi cookie e il suo accesso: idle, active, login_needed, paused, stopped o expired.

Filtri tag e batch di riproduzione

I media possono avere fino a 32 tag unici, ciascuno da 1 a 32 lettere o cifre. Sostituisci l’intero set con screenrig media update med_ID --tags Summer,Drinks. --tag Summer lo sostituisce con un solo tag; --clear-tag cancella ogni tag. media list --tag Summer corrisponde all’appartenenza ovunque nel set. I tag sono case-sensitive e non sono mai autorizzazioni.

Un selettore dinamico può usare un tag o un oggetto filtro tags:

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

all richiede ogni tag elencato, any ne richiede almeno uno, e none esclude qualsiasi tag elencato. I gruppi presenti si combinano con AND; i gruppi omessi non impongono condizioni. Fornisci almeno un gruppo non vuoto. Ogni gruppo accetta fino a 32 tag unici. tag e tags sono mutuamente esclusivi. Un filtro solo none seleziona tutti i media pronti di quel primitivo eccetto i tag esclusi. I selettori immagine selezionano immagini e i selettori video selezionano video.

Il pool di candidati contiene fino a 1.024 contenuti multimediali pronti per selettore, con 1.024 riferimenti multimediali nell’intero snapshot del ciclo. Un match più grande restituisce un errore; restringere i filtri. batch_size è un limite separato di 1–1.024 elementi per visita pagina. Su una pagina media_end, one_at_a_time: false riproduce il lotto successivo in sequenza; omettere batch_size riproduce il pass rimanente. one_at_a_time: true riproduce un elemento per apparizione e consente solo una dimensione lotto omessa o batch_size: 1. Durata, applicazione e pagine audio_end richiedono one_at_a_time: true. Le immagini su media_end richiedono anche dwell_ms; i video non possono loopare su quella pagina.

Il lettore risolve ogni primitiva multimediale dinamica in una richiesta all’avvio della playlist e a ogni ciclo. L’appartenenza è congelata durante il ciclo. Caricamenti, rimozioni, modifiche di tag e limiti di disponibilità non rigenerano il manifesto. Al prossimo aggiornamento, elementi rimossi o esclusi lasciano la coda in sospeso; nuove corrispondenze si uniscono quando il passaggio corrente termina. Un lotto finale può contenere meno elementi di quelli richiesti; non si ricarica dal passaggio successivo. L’ordine dei nomi file ordina per nome file, poi ID media. L’ordine casuale mescola una volta per passaggio completo, preservando l’ordine rimanente tra aggiornamenti ciclo. L’ordine ponderato segue i suoi pesi, più sotto. Il cursore è locale a schermo, playlist, pagina e primitiva, persiste al riavvio e si resetta se cambiano filtro, ordine o politica batch. La riproduzione offline usa l’ultimo snapshot riuscito. Corrispondenze vuote saltano la primitiva e eventuali pagine vuote risultanti.

Salva l’oggetto selettore sopra come selector.json, quindi ispeziona il suo catalogo candidato corrente prima di pubblicare:

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

L’anteprima restituisce matched_count, ordinata per nome file candidates con ID media e tag, e la policy selector normalizzata. Con ordine casuale mostra il pool e la policy di shuffle; non sceglie lo shuffle del lettore, non avanza un cursore, non crea un permesso di riproduzione né modifica un manifest. Con ordine ponderato restituisce per ogni candidato weight e share_percent, oltre a cycle. --rect WxH (API rect: {width, height}) è la dimensione dello slot ed è obbligatorio con fit: "aspect"; le corrispondenze escluse sono elencate in excluded con il motivo aspect_mismatch. I selettori di immagini passano --primitive image. L’API è POST /api/selectors/preview con { "primitive": "video", "selector": ... }. Usa il progetto autenticato e le stesse regole di corrispondenza della riproduzione. Le modifiche al catalogo dopo l’anteprima si risolvono al prossimo ciclo di riproduzione.

L’esportazione statica del bundle congela le corrispondenze dinamiche come ID esatti. Mantiene la riproduzione uno alla volta o completa; una sequenza runtime limitata con batch_size e one_at_a_time: false richiede di rimuovere quel campo o scegliere ID espliciti prima dell’esportazione. Questo evita di perdere silenziosamente un cursore batch runtime in un bundle statico.

Rotazione ponderata e adattamento alle proporzioni

order: "weighted" ruota i contenuti di uno slot in base al peso, così ogni sponsor mantiene la sua quota di riproduzioni. weights associa un ID media (med_...) o tag:NAME a un intero da 1 a 1.000, con al massimo 64 chiavi. Funziona con by uguale a all, tag o folder:

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

Pesi di 50, 30 e 20 assegnano esattamente 5, 3 e 2 riproduzioni ogni 10, a ogni ciclo, e un riavvio riprende a metà ciclo. Il peso di un elemento è la sua chiave ID media, se presente; altrimenti la prima chiave tag:NAME, in ordine alfabetico, tra i tag che porta, divisa in parti uguali tra gli elementi della selezione che la portano, così la quota di uno sponsor resta la stessa qualunque sia il numero dei suoi contenuti; altrimenti l’elemento conta come un gruppo a sé con peso 1. Un ciclo è al massimo di 4.096 riproduzioni; le quote vengono arrotondate a esso solo quando il rapporto esatto richiede un ciclo più lungo.

L’ordine ponderato riproduce un elemento per visita, quindi imposta one_at_a_time: true o batch_size: 1. weights è obbligatorio con l’ordine ponderato e consentito solo con esso; altrimenti la scrittura restituisce invalid_request. I lettori web, Android, Apple, Windows e Linux implementano l’ordine ponderato dalle versioni che dichiarano la capacità host selector.weighted. Un lettore più vecchio riproduce il selettore in ordine casuale e la diagnostica del manifest riporta selector_order_downgraded.

fit: "aspect" su un selettore dinamico mantiene solo i file il cui rapporto larghezza/altezza è entro il 5% di quello del rettangolo dello slot, video wall o cornice di display inclusi, letto quando il selettore viene risolto. Uno slot verticale non riproduce mai un file orizzontale. Non serve alcuna modifica al lettore.

screenrig media selector-preview stampa la quota attesa di ogni selettore ponderato o adattato per proporzioni, e l’editor di pagine della dashboard mostra la stessa tabella nell’inspector. L’esportazione statica del bundle congela un selettore ponderato come ID esatti in ordine di nome file; i pesi non vengono mantenuti.

Token dello schermo nei selettori di tag

Il tag di un selettore di tag, e ogni voce del suo filtro tags, può essere {screen.field.NAME} o {screen.id}, l’identificatore dello schermo senza il prefisso scr_, che è un tag. Il server compila il token per ogni schermo quando costruisce il manifest e lo snapshot dei selettori di quello schermo, così una sola playlist riproduce i media propri di ciascuno schermo. Assegna ai media il tag Lobby o Garage, imposta il campo di ogni schermo con screenrig screen update scr_ID --field zone=Lobby e assegna allo slot questo selettore:

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

Il valore compilato segue le regole dei tag: da 1 a 32 lettere o cifre. Uno schermo senza il campo, o il cui valore non è un tag, non seleziona nulla: non riproduce alcun file da quello slot e la diagnostica del manifest riporta screen_fact_missing o screen_fact_invalid. Modificare un campo rigenera il manifest di quello schermo. Un selettore con token non può essere visualizzato in anteprima (media selector-preview richiede un tag concreto) né congelato da playlist export.

Token dello schermo negli indirizzi iframe e nei parametri dell'applicazione

src e fallback_src di un iframe possono contenere token dello schermo nel percorso, nella query o nel frammento di un indirizzo http o https, e lo stesso vale per il params facoltativo di una primitiva application: fino a 16 nomi di 1-32 lettere minuscole, cifre o trattini bassi (ticket e policy sono riservati) con valori fino a 512 caratteri. Il server li compila per ogni schermo:

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

La scrittura memorizza il modello così come è scritto, parentesi graffe comprese. Il manifest di ogni schermo porta il proprio indirizzo, con ogni valore in percent-encoding per la sua posizione nell'URL: un kiosk_id di B 2&3 diventa B%202%263. Un token nello schema, nelle credenziali, nell'host o nella porta, o in un link YouTube, un link a documenti Google o Microsoft o un indirizzo di vista BI, è invalid_request a src (o fallback_src). La pubblicazione salta il controllo di framing per un src con modello, e le anteprime mostrano il modello così come è scritto.

Uno schermo che non ha un valore (un campo non impostato, nessuna posizione), o i cui valori compongono un indirizzo di oltre 2048 caratteri o con un segmento di percorso . o .., non riceve tale iframe o applicazione, e le diagnostiche del suo manifest riportano screen_fact_missing o screen_fact_invalid; una pagina rimasta vuota viene eliminata. Ogni scrittura che raggiunge un tale schermo (una scrittura di playlist, screen assign, screen update, un'assegnazione di flotta, una revisione approvata) risponde con un'avvertenza screen_fact_missing che indica i token, i primi 20 id di schermo e quanti sono. Modificare un campo o la posizione rigenera il manifest degli schermi interessati.

Per un'applicazione, ogni parametro compilato viene aggiunto all'indirizzo di avvio dopo ticket, in percent-encoding, per al massimo 4096 caratteri in totale, così l'applicazione lo legge da location.search (SDK). I parametri di avvio raggiungono l'app web Player e i Player che la eseguono (Samsung Tizen, BrightSign, LG webOS e Vega); i Player Qt, Android, Apple e Windows caricano l'applicazione dal pacchetto locale e non ne inviano. Il campo url di un modello può essere un intero src di iframe, e il suo valore può contenere a sua volta token dello schermo, compilati alla costruzione del manifest. Un selettore di tag usa {screen.id} e {screen.field.NAME} allo stesso modo (sopra). Le schede mantengono i propri token {screen.…}.

Disponibilità dei media

screenrig media availability med_ID --file rule.json imposta quando i selettori dinamici (all, tag e folder) possono scegliere un file. --clear rimuove la regola e --expect-rev N protegge la revisione del media. L’API è PATCH /api/media/{id}/availability con If-Match e { "availability": {...} | null }. Impostare una regola richiede l’accesso Manage; una credenziale Propose riceve insufficient_access.

La regola usa la grammatica oraria della programmazione, letta nel fuso orario di ogni schermo, e contiene almeno un membro: from e until (civile YYYY-MM-DDTHH:MM, until esclusivo), windows (settimanale {days, start, end}), monthly ({day} o {nth, weekday}, ciascuno con start e end facoltativi), dates ({date, start, end}) e except (date che rimuovono un’occorrenza, comprese le code oltre la mezzanotte). Non ha né data né interaction. Il contenuto di uno sponsor per il lungo weekend, disponibile solo nelle sere dei giorni feriali all’interno dell’intervallo:

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

Solo i selettori leggono la regola: un selettore esplicito con id o ids la ignora, così come i riferimenti media delle card, l’audio della colonna sonora e i contenuti pubblicitari. Un file esce dalla selezione e vi rientra al successivo ciclo della playlist di ogni schermo, entro circa un minuto dal limite. Nessuna revisione di playlist o manifest cambia e un lettore offline mantiene l’ultima selezione fino alla riconnessione. screenrig media selector-preview --timezone ZONE (UTC per impostazione predefinita) elenca in excluded i file fuori dalla loro regola in quel momento, con il motivo outside_window.

Torna al riferimento CLI di screenRIG.