Contenuti multimediali
Un oggetto multimediale è un’immagine fissa, una clip o una traccia audio MP3, archiviato come esattamente una rendition. Non c’è un fallback per dispositivo, quindi ogni schermo deve decodificare ciò che archivia media upload.
Le cartelle media organizzano la libreria. Un ID cartella inizia con mfd_ e un ID file con med_. Un caricamento arriva alla radice della libreria a meno che --folder non nomini una cartella, media move e media folder update riorganizzino l’albero, e un selettore playlist by:folder riproduca i file direttamente dentro una cartella, non quelli delle sue sottocartelle. Un’organizzazione contiene al massimo 1000 cartelle in tutti i suoi progetti, annidate fino a 10 livelli, con nomi da 1 a 100 caratteri.
Un media mantiene il suo ID quando il file cambia: media replace sostituisce il file sul posto, così ogni playlist e pianificazione che lo usa riproduce il nuovo, e media versions elenca tutti i file che l’elemento ha avuto.
media upload#
Converti un file locale in byte di consegna, caricalo e attendi che l’oggetto sia pronto.
media upload <file> [--content-type TYPE] [--tag TAG] [--folder ID] [--no-wait] [--poll-ms MS]
[--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<file> | path | sì | nessuno | Il frame statico sorgente, clip o traccia audio. Il nome file diventa il nome leggibile in elenchi, playlist e report di riproduzione, quindi nominarlo per ciò che mostra. |
--content-type TYPE | string | no | il tipo dell’estensione del file | Dichiara il tipo di media della sorgente per un file la cui estensione non lo indica. Un tipo che contraddice i byte del file viene rifiutato (usage_error, uscita 2) prima di qualsiasi conversione. |
--tag TAG | string | no | nessuno | Da uno a 32 lettere o cifre, corrispondenti a ^[A-Za-z0-9]{1,32}$. I trattini sono rifiutati. Un tag è ciò che rende media list --tag TAG una mappa affidabile da nome file a ID. |
--folder ID | string | no | radice della libreria | Una cartella media mfd_ esistente, controllata prima di iniziare qualsiasi lavoro. Il file vi arriva quando è pronto, in seguito non si sposta nulla, e data.folder_id la segnala. Funziona con --no-wait. Un uploader deve indicare una delle sue cartelle; vedi Uploader. |
--no-wait | boolean | no | spento | Restituisci non appena il commit è accettato. L’oggetto non è ancora pronto; termina con operations wait. |
--poll-ms MS | integer | no | 1000 | Intervallo tra i poll di operazione in attesa. |
--timeout MS | integer | no | 120000 | Scadenza per l’attesa. Limita anche ogni richiesta sottostante. |
--no-transcode | boolean | no | spento | Carica i byte sorgente senza modificarli. ffmpeg, ffprobe e cwebp non vengono eseguiti. Il file deve essere già un PNG, JPEG, WebP, GIF, MP4, WebM o MP3, e WebP senza perdita è comunque rifiutato. Non si può combinare con --codec, --max-fps, --max-edge, --webp-quality, --preset o --no-audio. |
--codec | string | no | h264 | h264 o hevc. Usa hevc solo quando ogni schermo che riprodurrà il clip è un Player nativo. |
--max-fps N | number | no | 30 | Frequenza di fotogrammi di uscita costante. Ogni video è codificato esattamente a questa frequenza indipendentemente dalla frequenza sorgente, quindi i clip consecutivi non cambiano mai frequenza. Maggiore di 0 e al massimo 240. |
--max-edge PIXELS | integer | no | 3840 | Vincolo applicato a ogni bordo, da 16 a 3840. Il rapporto d’aspetto è preservato e una sorgente più piccola non viene mai ingrandita. |
--webp-quality | integer | no | 90 | Qualità immagine statica per la codifica WebP, da 1 a 100. |
--preset | string | no | non impostato | signage-1080p30 o signage-4k30. Dimensione video orientata e costante a 30 fps. --max-edge e --max-fps possono restringere un preset ma non ingrandirlo. Solo video; non può combinarsi con --no-transcode. |
--no-audio | boolean | no | spento | Ometti la traccia audio dalla consegna video. Solo video; non può combinarsi con --no-transcode. |
--no-progress | boolean | no | spento | Non emettere output di avanzamento. L’avanzamento va sempre su stderr; stdout resta riservato all’unico risultato. |
screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoopIl video diventa un MP4: profilo High H.264 al livello 4.2, 5.1 o 5.2, il più basso adatto a dimensioni e frequenza, oppure profilo Main H.265 al livello 5.1 o 5.2 con --codec hevc, in yuv420p taggato Rec. 709, al massimo 3840 per 2160 pixel per fotogramma. Una sorgente HDR è mappata a tono Rec. 709. L’audio, se presente nella sorgente, è AAC a 192 kbit/s, 48 kHz, stereo.
Le immagini statiche diventano WebP lossy a qualità 90, mantenendo l’alpha se presente nella sorgente. Una sorgente animata cicla all’infinito. Un WebP che già rispetta il limite di dimensione viene passato senza ricodifica.
L’audio diventa un MP3 per la colonna sonora della playlist. Una sorgente MP3 si carica senza modifiche; sorgenti WAV, AAC, M4A, OGG e FLAC si convertono in MP3 a 128 kb/s, che richiede una build ffmpeg con libmp3lame. Una traccia dura da 1 secondo a 3 ore. playlist init trasforma gli input audio in tracce colonna sonora invece che pagine. L’oggetto pronto è un media audio con durata. Non può essere posizionato su una pagina; nominarlo come colonna sonora audio nella playlist.
L’ID dell’oggetto pronto è data.media_id. Lo stesso valore è data.id e data.operation.result.media_id. Questo ID è ciò che prende un selettore di playlist.
Un media pronto con gli stessi byte, nome file e tag viene restituito invece di essere caricato di nuovo (data.reused è true), quindi rieseguire un caricamento interrotto restituisce il suo ID media. data.timing riporta i millisecondi per fase: prepare_ms (conversione e hash), declare_ms, transfer_ms, commit_ms e processing_ms (fino allo stato pronto, preciso quanto --poll-ms; assente con --no-wait).
Un nome file con poche informazioni come video.mp4 aggiunge un avviso generic_filename all’involucro. Il caricamento ha comunque successo e la CLI non rinomina mai il file; scegli il nome prima di eseguire il comando.
La conversione esegue ffmpeg e ffprobe da PATH, o dai percorsi assoluti in SCREENRIG_FFMPEG e SCREENRIG_FFPROBE. Le immagini preferiscono il codificatore ffmpeg libwebp e ricadono su cwebp su PATH o SCREENRIG_CWEBP. Esegui doctor prima del primo caricamento di una sessione.
--preset signage-1080p30 limita il lato lungo a 1920, il lato corto a 1080 e la frequenza a 30 fps costanti. signage-4k30 limita il lato lungo a 3840, il lato corto a 2160 e la frequenza a 30 fps costanti. Entrambi funzionano con contenuti orizzontali, verticali e quadrati. --no-audio omette la codifica audio per clip silenziose. Queste opzioni si applicano solo al video.
screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audioscreenrig media upload ./menu.png --folder mfd_01EXAMPLEFOLDER000000000media upload-batch --folder inserisce ogni elemento caricato nella cartella allo stesso modo.
Un’immagine o un video può essere largo o alto fino a 16383 pixel e avere 67.108.864 pixel (8192 per 8192) in un fotogramma; uno più grande viene rifiutato con invalid_request. La conversione predefinita adatta ogni lato a 3840 pixel, quindi carica un master ultra-largo come 9216 per 2160 o 12000 per 540 con --no-transcode. Un caricamento video può essere al massimo il più grande caricamento video del piano del progetto, che project capabilities riporta come media_video_bytes (vedi Prezzi); un video più grande viene rifiutato prima di essere letto, quindi accorcia prima il clip. La CLI codifica il video con qualità fissa, quindi un video lungo può comunque superare il limite dopo la codifica e viene allora rifiutato; con --no-transcode il file stesso deve rientrare nel limite.
Un trasferimento verso l’archiviazione interrotto viene ritentato fino a 4 volte finché il suo URL di caricamento è valido. Se continua a non riuscire, l’errore indica l’operation_id del caricamento e il caricamento viene annullato così da non occupare archiviazione; con --idempotency-key viene mantenuto per la riesecuzione. Esegui di nuovo lo stesso comando.
Con accesso Proponi, o quando il progetto richiede revisione per modifiche agent, un nuovo caricamento attende la revisione di una persona prima che un tag, una cartella o un selettore all lo riproduca; vedi Revisioni.
media upload-batch#
Carica molti file locali da un manifesto, riprendendo da un file di stato.
media upload-batch <manifest.json> [--state FILE] [--concurrency N] [--tag TAG] [--folder ID]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc]
[--max-fps N] [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<manifest.json> | path | sì | nessuno | { "items": [ { "path": "./a.png", "tag"?: "Lobby", "content_type"?: "image/png" } ] } con da 1 a 1000 elementi. I percorsi sono relativi al file manifest. |
--state FILE | path | no | file privato accanto alla configurazione | Un file JSON 0600 indicizzato dal SHA-256 dei byte locali di ogni file sorgente; per impostazione predefinita, un file per progetto, indirizzo API e manifest. Gli elementi già presenti con un media_id sono segnalati come resumed. Non condividere un file di stato tra progetti. |
--concurrency N | integer | no | 4 | Caricamenti paralleli, da 1 a 8. |
--no-transcode | boolean | no | spento | Carica i byte sorgente senza modificarli, come fa media upload. Non si può combinare con --codec, --max-fps, --max-edge, --webp-quality, --preset o --no-audio. |
--poll-ms MS | integer | no | 1000 | Intervallo tra i poll di operazione in attesa. |
--timeout MS | integer | no | 120000 | Scadenza per l’attesa. Limita anche ogni richiesta sottostante. |
--codec | string | no | h264 | h264 o hevc. Usa hevc solo quando ogni schermo che riprodurrà il clip è un Player nativo. |
--max-fps N | number | no | 30 | Frequenza di fotogrammi di uscita costante. Ogni video è codificato esattamente a questa frequenza indipendentemente dalla frequenza sorgente, quindi i clip consecutivi non cambiano mai frequenza. Maggiore di 0 e al massimo 240. |
--max-edge PIXELS | integer | no | 3840 | Vincolo applicato a ogni bordo, da 16 a 3840. Il rapporto d’aspetto è preservato e una sorgente più piccola non viene mai ingrandita. |
--webp-quality | integer | no | 90 | Qualità immagine statica per la codifica WebP, da 1 a 100. |
--preset | string | no | non impostato | signage-1080p30 o signage-4k30. Dimensione video orientata e costante a 30 fps. --max-edge e --max-fps possono restringere un preset ma non ingrandirlo. Solo video; non può combinarsi con --no-transcode. |
--no-audio | boolean | no | spento | Ometti la traccia audio dalla consegna video. Solo video; non può combinarsi con --no-transcode. |
--tag TAG | string | no | nessuno | Applicato quando un elemento omette il proprio tag. |
--folder ID | string | no | radice della libreria | Una cartella media mfd_ esistente, controllata prima di iniziare qualsiasi lavoro. Ogni elemento vi arriva quando è pronto, e data.folder_id la segnala. Un uploader deve indicare una delle sue cartelle. |
--no-progress | boolean | no | spento | Non emettere output di avanzamento. |
screenrig media upload-batch ./images.json --state ./upload-state.jsonLa busta contiene data.items[] in ordine di manifest; ciascuno con path, source_filename, sha256, outcome (accepted o resumed), e media_id. data.failed[] contiene gli elementi non consegnati, ciascuno con il suo path e il suo problem; data.accepted, data.resumed, data.attempts, data.rate_limited, data.wait_ms e data.transfer_ms contano l’esecuzione. Un elemento viene ritentato fino a 8 volte, con attesa tra i tentativi, finché la risposta è un limite di frequenza o un errore del server.
In caso di errori, il codice di uscita segue l’ultimo elemento non riuscito: 7 per un limite di frequenza, 9 per un errore del server, 2 per un errore di utilizzo, altrimenti 8. Esegui di nuovo lo stesso comando con lo stesso manifest per caricare solo ciò che non è stato consegnato.
media replace#
Sostituisce sul posto il file di un media. Il suo ID, le sue playlist e le sue pianificazioni continuano a funzionare.
media replace <id> <file> [--expect-rev REVISION] [--note TEXT] [--content-type TYPE] [--no-wait]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
<file> | path | sì | nessuno | La nuova immagine, il nuovo clip o la nuova traccia audio. Deve essere dello stesso tipo del media: immagine per immagine, video per video, audio per audio. Verificato prima che inizi qualsiasi lavoro (usage_error, codice di uscita 2). |
--expect-rev REVISION | string | no | nessuno | Precondizione di revisione facoltativa. Un valore obsoleto fornito è revision_conflict e il caricamento dichiarato viene annullato: leggi media show ID ed esegui di nuovo il comando. |
--note TEXT | string | no | nessuno | Conservata con la nuova versione e mostrata alla persona che la revisiona. Al massimo 280 caratteri. |
--content-type TYPE | string | no | rilevato dai byte caricati | Dichiarare il tipo di media personalmente invece di lasciare che la CLI lo rilevi. |
--no-wait | boolean | no | spento | Restituisci non appena la sostituzione è accettata. Il nuovo file non è ancora in uso; termina con operations wait. |
--poll-ms MS | integer | no | 1000 | Intervallo tra i poll di operazione in attesa. |
--timeout MS | integer | no | 120000 | Scadenza per l’attesa. Limita anche ogni richiesta sottostante. |
--no-transcode | boolean | no | spento | Carica i byte sorgente senza modificarli. ffmpeg, ffprobe e cwebp non vengono eseguiti. Il file deve essere già un PNG, JPEG, WebP, GIF, MP4, WebM o MP3, e WebP senza perdita è comunque rifiutato. Non si può combinare con --codec, --max-fps, --max-edge, --webp-quality, --preset o --no-audio. |
--codec | string | no | h264 | h264 o hevc. Usa hevc solo quando ogni schermo che riprodurrà il clip è un Player nativo. |
--max-fps N | number | no | 30 | Frequenza di fotogrammi di uscita costante. Ogni video è codificato esattamente a questa frequenza indipendentemente dalla frequenza sorgente, quindi i clip consecutivi non cambiano mai frequenza. Maggiore di 0 e al massimo 240. |
--max-edge PIXELS | integer | no | 3840 | Vincolo applicato a ogni bordo, da 16 a 3840. Il rapporto d’aspetto è preservato e una sorgente più piccola non viene mai ingrandita. |
--webp-quality | integer | no | 90 | Qualità immagine statica per la codifica WebP, da 1 a 100. |
--preset | string | no | non impostato | signage-1080p30 o signage-4k30. Dimensione video orientata e costante a 30 fps. --max-edge e --max-fps possono restringere un preset ma non ingrandirlo. Solo video; non può combinarsi con --no-transcode. |
--no-audio | boolean | no | spento | Ometti la traccia audio dalla consegna video. Solo video; non può combinarsi con --no-transcode. |
--no-progress | boolean | no | spento | Non emettere output di avanzamento. L’avanzamento va sempre su stderr; stdout resta riservato all’unico risultato. |
screenrig media replace med_01EXAMPLEIMAGE0000000000 ./menu-v2.png
screenrig media replace med_01EXAMPLEVIDEO0000000000 ./intro.mp4 --expect-rev 3 --note "Spring cut"Il file mantiene il suo ID, i tag e la cartella, quindi ogni playlist e programmazione che lo nomina riproduce il nuovo file al manifest successivo, e anche i selettori per tag, cartella e all lo raccolgono. Nulla viene riprogrammato. Il comando esegue gli stessi passaggi di media upload (conversione, il limite di byte video del piano, i limiti di dimensioni, il limite di archiviazione del piano, il trasferimento firmato) e poi sostituisce invece di aggiungere un nuovo file. Non accetta --tag o --folder.
Per impostazione predefinita il comando attende l’elaborazione. data.media_id e data.id sono l’ID del media, data.version è il numero del nuovo file in media versions e data.revision è la nuova revisione del media. data.warnings, data.operation, data.upload, data.transcode e i tempi sono riportati come per media upload, e l’ID dell’operazione è nella risposta. Con --no-wait, data.operation è l’operazione accettata, e data.version e data.warnings sono assenti.
Un cambio di proporzioni è consentito. La risposta contiene un avviso aspect_ratio_changed e data.warnings[].playlists indica le playlist che usano il media, quindi controlla come appaiono. Un file con gli stessi byte di quello attuale viene rifiutato con resource_conflict (codice di uscita 13).
Ogni file precedente rimane nella cronologia del media e conta nei byte archiviati finché la sua versione non viene eliminata; vedi media versions.
Con accesso Propose, o quando il progetto richiede revisione per le modifiche dell’agente, la sostituzione attende una persona e il comando riesce (codice di uscita 0): data.status è pending_review, data.review_id indica la revisione, l’avviso pending_review fornisce il suo URL e data.next è screenrig reviews show ID. Il media continua a riprodurre il file attuale finché una persona non approva; dille quindi che è in attesa e non ripetere la scrittura. Una sostituzione più recente dello stesso media sostituisce quella in attesa. Vedi Revisioni.
media versions#
Elenca i file che un media ha avuto, con il file in uso per primo.
media versions <id> [--limit N] [--cursor CURSOR]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--limit N | integer | no | ogni pagina | Leggi una pagina di questo numero di versioni, da 1 a 100. |
--cursor CURSOR | string | no | nessuno | Leggi la pagina successiva al data.next_cursor della pagina precedente. |
screenrig media versions med_01EXAMPLEIMAGE0000000000data.items ha una voce per ogni file che il media ha avuto: number, current, filename, source_filename, content_type, sha256, bytes, width, height, duration_ms, codecs, source (upload, replace, sync o restore), note, by (tipo person, agent, client o sync, con ID e nome), restored_from e created_at. Il file in uso viene per primo (current: true), poi gli altri dal più recente. La versione 1 è il primo caricamento; ogni sostituzione, ripristino o modifica della sincronizzazione dei media aggiunge il numero successivo.
Senza --limit e --cursor vengono lette tutte le pagine e data.next_cursor è null. Con uno dei due viene letta una pagina: finché data.next_cursor è una stringa, esegui di nuovo il comando con --cursor impostato su di essa. Basta l’accesso di sola lettura. I byte di una versione precedente restano archiviati e contano nei byte archiviati del progetto finché media version delete non li elimina; non c’è limite al numero di versioni conservate, e i byte archiviati oltre l’archiviazione gratuita del piano sono fatturati come qualsiasi altra archiviazione.
media restore#
Rimette in uso una versione precedente come nuova versione.
media restore <id> --number N [--expect-rev REVISION] [--note TEXT]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--number N | integer | sì | nessuno | Il numero della versione da rimettere in uso, come lo elenca media versions. |
--expect-rev REVISION | string | no | nessuno | Precondizione di revisione facoltativa. Un valore obsoleto fornito è revision_conflict: leggi media show ID ed esegui di nuovo il comando. |
--note TEXT | string | no | nessuno | Conservata con la nuova versione e mostrata alla persona che la revisiona. Al massimo 280 caratteri. |
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2 --expect-rev 5 --note "Back to the winter menu"Il media mantiene il suo ID e passa a una nuova revisione, e ogni playlist e pianificazione che lo nomina riproduce di nuovo quel file. La versione che copia resta nella cronologia e condivide i suoi byte; la nuova versione conta nei byte archiviati come qualsiasi altra. data.media è il media e data.warnings contiene aspect_ratio_changed, che indica le playlist che usano il media, quando il file ripristinato ha proporzioni diverse.
La versione in uso non può essere ripristinata (resource_conflict, codice di uscita 5) e una versione sconosciuta è not_found (codice di uscita 4). Con accesso Propose, o quando il progetto richiede revisione per le modifiche dell’agente, il ripristino attende una persona e il comando riesce (codice di uscita 0): data.status è pending_review con data.review, l’avviso pending_review fornisce il suo URL e data.next è screenrig reviews show ID. Il media continua a riprodurre il file attuale finché una persona non approva, quindi non ripetere la scrittura.
media version delete#
Elimina una versione precedente e i suoi byte archiviati.
media version delete <id> --number N| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--number N | integer | sì | nessuno | Il numero della versione da eliminare, come lo elenca media versions. |
screenrig media version delete med_01EXAMPLEIMAGE0000000000 --number 2Il record della versione scompare e i suoi byte lasciano subito i byte archiviati del progetto. L’oggetto archiviato viene rimosso dopo 24 ore, a meno che un’altra versione o il file in uso contenga lo stesso file. Una versione eliminata non può essere ripristinata. La versione in uso non può essere eliminata e nessuna versione può essere eliminata mentre una sostituzione del media è in attesa di revisione; entrambi i casi sono resource_conflict (codice di uscita 5), e media versions ID mostra quale versione è in uso. Una versione sconosciuta è not_found (codice di uscita 4). L’eliminazione richiede l’accesso Manage: una credenziale Propose viene rifiutata con insufficient_access, e l’eliminazione non viene mai proposta per revisione.
media show#
Leggi un oggetto contenuti multimediali, inclusa la sua revisione corrente.
media show <id>| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
screenrig media show med_01EXAMPLEIMAGE0000000000media download#
Scrivi una resa memorizzata su disco per ispezione. Mai stampare i byte.
media download <id> [--output FILE]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--output FILE | path | no | ./<id>.<ext> nella directory corrente | Un percorso file, non una cartella. Un file esistente viene sovrascritto. L’estensione segue il tipo di contenuto. |
screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webpLa risposta riporta media_id, path, bytes, sha256, content_type, primitive, filename, source_filename facoltativo e width / height. Non contiene mai pixel. Usala per controllare un’immagine prima che vada sullo schermo.
media list#
Elenca gli oggetti multimediali, filtrabili per tag, tipo primitivo e cartella.
media list [--tag TAG] [--primitive image|video|audio] [--folder ID|root] [--library]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
--tag TAG | string | no | nessuno | Corrispondenza ^[A-Za-z0-9]{1,32}$. Gli oggetti non etichettati sono omessi ogni volta che questo filtro è presente. |
--primitive | string | no | tutti | image, video o audio. Restringi l’elenco a still, clip o tracce audio. |
--folder ID|root | string | no | ogni cartella | Solo file direttamente dentro questa cartella mfd_, non le sue sottocartelle, o con root solo file alla radice della libreria. L’API applica il filtro. |
--library | boolean | no | spento | Elenca invece i contenuti multimediali della Libreria dell’organizzazione, in sola lettura: le righe riportano library: true. Usa i loro ID nelle pagine della playlist; modificali solo nel progetto Libreria. |
screenrig media list --tag LobbyLoop --primitive video
screenrig media list --folder mfd_01EXAMPLEFOLDER000000000
screenrig media list --libraryOgni riga contiene folder_id, che non è presente alla radice della libreria.
media selector-preview#
Mostra in anteprima quali file pronti un selettore media dinamico trova ora, senza pubblicare una playlist né far avanzare un Player.
media selector-preview <selector.json> --primitive image|video [--rect WxH] [--timezone IANA]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<selector.json> | path | sì | nessuno | Un file JSON con un selettore media all, tag o folder, oppure - per stdin. Un tag con un token dello schermo non può essere visualizzato in anteprima. |
--primitive | string | sì | nessuno | image o video: il tipo di file che il selettore trova. |
--rect WxH | string | con fit: "aspect" | nessuno | La dimensione del rettangolo del primitivo, ad esempio 1080x1920, con entrambi i numeri maggiori di 0. |
--timezone IANA | string | no | UTC | Il fuso orario in cui vengono lette le regole di disponibilità dei file, ad esempio America/New_York. |
screenrig media selector-preview selector.json --primitive video
screenrig media selector-preview selector.json --primitive image --timezone America/New_YorkLe chiavi del selettore (order, batch_size, one_at_a_time, weights e fit) sono descritte in Filtri tag e batch di riproduzione e Rotazione ponderata e adattamento alle proporzioni.
La risposta contiene matched_count, i candidates ordinati per nome file (media_id, filename, tags, width, height), il selector normalizzato e, in excluded, i file esclusi con il loro reason: aspect_mismatch per fit: "aspect" e outside_window per un file la cui regola di disponibilità non vale ora. Con order: "weighted", ogni candidato contiene weight e share_percent, e cycle è il numero di riproduzioni dopo le quali ogni elemento ha suonato esattamente il proprio peso. Più di 1024 corrispondenze danno invalid_request. Basta l’accesso in lettura. L’anteprima legge il progetto autenticato, non fa mai avanzare un cursore né modifica un manifest, e una modifica al catalogo successiva viene recepita al successivo confine di ciclo di ogni Player.
media update#
Sostituisce o cancella i tag di un oggetto. La sua regola di disponibilità si imposta con media availability.
media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--tag TAG | string | uno dei tre | nessuno | Il tag sostitutivo, da una a 32 lettere o cifre. Diventa l’unico tag dell’oggetto. |
--tags TAG1,TAG2 | string | uno dei tre | nessuno | L’insieme di tag sostitutivo: da 1 a 32 tag univoci separati da virgole, ciascuno da una a 32 lettere o cifre. |
--clear-tag | boolean | uno dei tre | spento | Rimuove tutti i tag e lascia l’oggetto senza tag. |
--expect-rev REVISION | string | no | nessuno | Precondizione opzionale di revisione. Ometti per scrivere la risorsa corrente. Un valore obsoleto fornito è revision_conflict: rifetch, reapply, retry. |
screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop
screenrig media update med_01EXAMPLEIMAGE0000000000 --tags Summer,DrinksCon accesso Proponi, o quando il progetto richiede revisione per modifiche agent, il rietichettamento di media approvati risponde a ok con avviso media_review_pending: gli schermi continuano a riprodurlo con i tag approvati finché una persona approva la modifica, e un rifiuto ripristina i tag. La revisione appare in reviews list entro pochi secondi; un rietichettamento che non modifica playlist approvate o in attesa di revisione si applica da solo. Vedi Revisioni.
media availability#
Imposta o cancella quando i selettori dinamici possono scegliere un file.
media availability <id> (--file FILE | --clear) [--expect-rev REVISION]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--file FILE | path | uno dei due | nessuno | Una regola di disponibilità JSON, oppure - per stdin. |
--clear | boolean | uno dei due | spento | Rimuove la regola; il file è sempre disponibile. |
--expect-rev REVISION | string | no | revisione corrente | Precondizione opzionale di revisione. Se omessa, il comando legge prima la revisione corrente del media. Un valore obsoleto fornito è revision_conflict: rileggere, riapplicare, riprovare. |
screenrig media availability med_01EXAMPLEIMAGE0000000000 --file rule.jsonI membri e il comportamento della regola sono descritti in Disponibilità dei media. Un file in attesa della revisione di una persona viene rifiutato con media_pending_review: decidi prima quella revisione.
media delete#
Elimina un oggetto media.
media delete <id> [--expect-rev REVISION]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID oggetto med_. |
--expect-rev REVISION | string | no | nessuno | Precondizione opzionale di revisione. Ometti per scrivere la risorsa corrente. Un valore obsoleto fornito è revision_conflict: rifetch, reapply, retry. |
screenrig media delete med_01EXAMPLEIMAGE0000000000media move#
Sposta file e cartelle multimediali in una cartella, o torna alla radice della libreria.
media move <id>... (--folder ID | --root)| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id>... | string | sì | nessuno | Uno o più ID file med_ e ID cartella mfd_, al massimo 1000 in totale. |
--folder ID | string | uno dei due | nessuno | La cartella di destinazione mfd_. |
--root | boolean | uno dei due | spento | Sposta alla radice della libreria. |
screenrig media move med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --folder mfd_01EXAMPLEFOLDER000000000
screenrig media move mfd_01EXAMPLEFOLDER000000000 --rootLo spostamento è una richiesta tutto o niente. Una cartella non può spostarsi dentro se stessa o una cartella al suo interno, e le cartelle si annidano al massimo a 10 livelli. Gli elementi già nella destinazione restano come sono. data.media e data.folders contano ciò che è stato spostato.
Spostare file cambia cosa riproducono i selettori by:folder delle loro vecchie e nuove cartelle, dalla risoluzione del selettore successivo di ogni schermo; spostare una cartella non cambia i file propri di nessuna cartella. Sotto Propose access, o quando il progetto richiede revisione per modifiche agente, ogni file spostato attende la revisione di una persona (reviews list) e le playlist approvate continuano a riprodurlo tramite la cartella con cui è stato approvato; vedi Revisioni.
media folder list#
Elenca le cartelle multimediali del progetto
media folder list [--library]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
--library | boolean | no | spento | Elenca invece le cartelle della Libreria dell’organizzazione, in sola lettura: le righe riportano library: true, e un selettore by:folder può indicarne una per riprodurne i file. |
screenrig media folder list
screenrig media folder list --libraryRestituisce tutte le cartelle del progetto, al massimo 1000, ordinate per nome: data.items con id, name, parent_id (null alla radice della libreria) e revision. Costruisci l’albero da parent_id. La cartella di un file è folder_id su media list e media show; è assente alla radice della libreria.
media folder show#
Leggi una cartella contenuti multimediali.
media folder show <id>| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID cartella mfd_. |
screenrig media folder show mfd_01EXAMPLEFOLDER000000000La busta contiene il name, parent_id e revision della cartella.
media folder create#
Crea una cartella contenuti multimediali nella radice della libreria o all’interno di un’altra cartella.
media folder create --name NAME [--parent ID]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
--name NAME | string | sì | nessuno | Da 1 a 100 caratteri, senza spazi. I nomi possono ripetersi. |
--parent ID | string | no | radice della libreria | La cartella mfd_ in cui crearla. |
screenrig media folder create --name Menus
screenrig media folder create --name Lunch --parent mfd_01EXAMPLEFOLDER000000000Un’organizzazione contiene al massimo 1000 cartelle in tutti i suoi progetti, annidate fino a 10 livelli. Una playlist riproduce i file di una cartella con un selettore by:folder.
media folder update#
Rinomina una cartella media o spostala con tutto il contenuto in un’altra cartella.
media folder update <id> [--name NAME] [--parent ID | --root] [--expect-rev REVISION]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID cartella mfd_. |
--name NAME | string | almeno uno tra --name, --parent, --root | invariato | Il nuovo nome, da 1 a 100 caratteri. |
--parent ID | string | almeno uno tra --name, --parent, --root | invariato | Sposta la cartella, con tutto il suo contenuto, in questa cartella mfd_. Non con --root. |
--root | boolean | almeno uno tra --name, --parent, --root | spento | Sposta la cartella nella radice della libreria. Non con --parent. |
--expect-rev REVISION | string | no | nessuno | Precondizione opzionale di revisione. Ometti per scrivere la risorsa corrente. Un valore obsoleto fornito è revision_conflict: rifetch, reapply, retry. |
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --name Archive
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --rootUna cartella non può spostarsi dentro se stessa o in una cartella al suo interno, e uno spostamento deve mantenere ogni cartella entro 10 livelli. Inviare i valori correnti è un’operazione nulla.
media folder delete#
Elimina una cartella media. I suoi file e cartelle vengono spostati di un livello verso l’alto.
media folder delete <id> [--expect-rev REVISION]| Parametro | Tipo | Obbligatorio | Predefinito | Note |
|---|---|---|---|---|
<id> | string | sì | nessuno | L’ID cartella mfd_. |
--expect-rev REVISION | string | no | nessuno | Precondizione opzionale di revisione. Ometti per scrivere la risorsa corrente. Un valore obsoleto fornito è revision_conflict: rifetch, reapply, retry. |
screenrig media folder delete mfd_01EXAMPLEFOLDER000000000Elimina solo la cartella. I suoi file e cartelle vengono spostati nel genitore, o nella radice della libreria se non ne ha uno. Un selettore by:folder che la nomina poi non corrisponde a nulla, quindi ripuntare prima quelle playlist.
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.
Un selettore folder, { "by": "folder", "folder_id": "mfd_…" }, riproduce i file pronti direttamente dentro una cartella media e nessuno delle sue sottocartelle; media folder list mostra gli ID. Accetta gli stessi order, one_at_a_time e batch_size di all e tag, ed eliminare una cartella sposta i suoi file di un livello in su e lascia il selettore vuoto.
Il pool di candidati contiene fino a 1.024 media pronti per selettore, con 1.024 riferimenti media nell’intero snapshot del ciclo. Una scrittura conta ogni selettore all, tag o folder come 32 di quei riferimenti e un selettore ids come la sua lunghezza. Una corrispondenza più ampia restituisce un errore; restringi i filtri. batch_size è un limite separato di 1–1.024 elementi per visita di pagina. Su una pagina media_end, one_at_a_time: false riproduce il batch successivo in sequenza; omettere batch_size riproduce il passaggio rimanente. one_at_a_time: true riproduce un elemento per apparizione e consente solo una dimensione batch omessa o batch_size: 1. Sulle pagine di durata, applicazione e audio_end ogni selettore all, tag, folder e ids con più id richiede one_at_a_time: true, e dwell_ms viene rifiutato. Le immagini su media_end richiedono inoltre dwell_ms; i video non possono ripetersi 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 e mescola una volta un selettore random. 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. La rotazione ponderata è una funzionalità Plus: senza di essa, una scrittura che imposta un peso che un elemento non ha già riceve feature_not_in_plan, mentre la rotazione uniforme, il mantenimento dei pesi salvati e la loro rimozione restano disponibili. Ogni Player riproduce l’ordine ponderato. A un Player che non dichiara la capacità host selector.weighted viene inviato random, e le diagnostiche del manifest riportano 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 file di un selettore ponderato e, con fit: aspect, elenca i file che esclude; 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. Un token può trovarsi accanto a lettere e cifre in un modello di al massimo 128 caratteri. 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:
| Token | Valore |
|---|---|
{screen.id} | L'identificatore dello schermo senza il prefisso scr_. |
{screen.name} | Il nome dello schermo. |
{screen.timezone} | Il fuso orario IANA effettivo dello schermo: il suo override, altrimenti la zona che il suo Player riporta, altrimenti UTC. |
{screen.field.NAME} | Il campo NAME dello schermo, da 1 a 32 lettere minuscole, cifre o trattini bassi. |
{screen.location.lat}, {screen.location.lon} | La sua posizione in gradi decimali. |
{screen.location.name}, {screen.location.address} | Il nome del luogo e l'indirizzo. |
{
"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, i parametri compilati, al massimo 4096 caratteri in totale in percent-encoding, la raggiungono in context.params su ogni Player (SDK). L’app web Player e i Player che la eseguono (Samsung Tizen, BrightSign, LG webOS e Vega) aggiungono inoltre ciascuno di essi all’indirizzo di avvio dopo ticket, in percent-encoding, così l’applicazione può leggere location.search. 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.…}.
Le primitive di applicazione di una stessa playlist che fissano la stessa versione portano gli stessi params.
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. Senza --expect-rev, il comando legge prima la revisione corrente del media. Un file in attesa della revisione di una persona viene rifiutato con media_pending_review.
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), con fino a 16 windows, 16 voci monthly, 100 dates e 100 date except. 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. media selector-preview con --timezone ZONE (UTC per impostazione predefinita) legge le regole in quel fuso ed elenca in excluded i file fuori dalla loro regola in quel momento, con il motivo outside_window.