Playlists: comandos da CLI

Playlists

Uma playlist é um documento JSON de páginas. playlist init prepara um documento de tela cheia a partir de entradas ordenadas. playlist create e playlist update leem esse documento de um arquivo; playlist patch, playlist rename e playlist page add|replace|remove alteram parte dele. A forma é resumida nos comandos.

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

O documento da playlist

Uma playlist é name (1 a 120 caracteres) mais pages (1 a 100), com uma trilha sonora audio opcional e um format opcional. Cada página contém id, canvas, transition, advance, visibility opcional, audio_cue opcional e primitives (1 a 24). Os IDs de página, de primitiva e de faixa são uma letra seguida de até 63 letras, dígitos, _ ou -; os IDs de página são únicos na playlist e os de primitiva em sua página. Um canvas recebe width e height de 1 a 1.000.000, um background e um viewport_fit opcional: veja Fundo e movimento da página.

Um format torna uma playlist um video wall, {displays, arrangement, orientation} com columns para um grid, ou uma faixa, {region, orientation}. Um video wall tem de 2 a 12 displays de 1920 x 1080 (1080 x 1920 em retrato), toda página comum tem o canvas do video wall, e o displays de uma primitiva nomeia os blocos que ela cobre no lugar de rect. Veja Video walls e Faixas. Uma página de slot de anúncio, {id, type: "adslot", adslot_id} com visibility opcional, não contém canvas nem primitivas; uma playlist contém no máximo 16 delas e mantém uma página comum sem visibility.

Um modelo adiciona fields ao documento, [{name, label, type, required, max_length?}] com type igual a text, media ou url, e pode marcar qualquer primitiva como locked: true. Uma página lê um campo como {field.NAME} nos params de um cartão (campos de texto e de endereço), como selector.media_id de uma imagem ou de um vídeo (um campo de mídia) ou como src inteiro de um iframe (um campo de endereço). Cada marcador deve nomear um campo declarado do tipo certo, cada campo deve ser lido e uma primitiva bloqueada não lê nenhum; playlist validate verifica isso offline. Só o proprietário ou um membro que possa aprovar altera uma primitiva bloqueada (primitive_locked). Um modelo declara no máximo 16 campos: name tem de 1 a 32 letras minúsculas, dígitos ou sublinhados, label até 60 caracteres, e o max_length de um campo de texto (padrão 200) até 2000. Um campo opcional de mídia ou de endereço deixado sem valor deixa de fora a primitiva que o lê. Declarar fields e travar uma primitiva fazem parte dos modelos de playlist, um recurso do Premium. Um format de video wall de 2 ou 3 telas exige o Plus, e um de 4 a 12 telas, o Enterprise. Um plano sem o recurso responde feature_not_in_plan com required_plan, enquanto uma gravação que mantém o que a playlist já tem continua liberada. Criar uma cópia a partir de um modelo está em todos os planos.

As seis primitivas são image, video enviado, stream ao vivo, iframe web e application, e card. Texto e moldura não são tipos de transmissão: coloque um card para texto ao vivo, ou envie uma imagem estática pronta que o seu agente criou e coloque-a como imagem.

Um stream usa uma ou duas fontes ordenadas com protocolos únicos e uma imagem pronta do mesmo projeto como fallback_media_id. Use no máximo um stream por página e avanço baseado em duração. HLS usa uma URL HTTPS pública; os Players Android e Qt se conectam diretamente aos feeds RTSP das câmeras, incluindo as credenciais. Consulte os detalhes dos transportes de câmera para saber quais formatos de URL cada Player abre; o multicast UDP/MPEG-TS direto opcional no Android e Qt usa um grupo IPv4 em 239/8 e uma porta. Uma fonte pode informar apenas sua url e deixar o esquema definir o protocolo. Outros Players selecionam a alternativa HLS ou exibem o fallback. Bytes do stream não são armazenados em cache para reprodução. O áudio é mudo por padrão; muted definido como false o reproduz, com as regras do som de um vídeo descritas abaixo. A importação e a exportação de pacote de playlist não suportam streams.

{
  "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"
}

Use este primitivo em uma página com advance: {"mode":"duration","after_ms":30000}. Substitua o feed de exemplo e o ID de fallback. Requisitos do Player e configuração do transporte.

Toda primitiva é plana: id, primitive, os campos próprios dessa primitiva, depois rect, layer, content_fit e enter e motion opcionais. Não há objeto de conteúdo aninhado. rect é x, y, width e height em unidades de canvas e layer um número inteiro de 0 a 1024. Um rect pode se estender além do canvas para sangria: os Players ajustam o conteúdo ao rect inteiro e depois cortam no canvas, então use content_fit cover ou fill para preencher o canvas visível. Um cartão é posicionado por layout e precisa de um rect apenas para free; em uma playlist de video wall displays substitui rect.

Primitivas de imagem e vídeo exigem selector. selector.by é id com um media_id pronto e one_at_a_time false, ids com 1 a 1.024 media_ids prontos únicos, all para todo objeto pronto dessa primitiva, tag correspondente a ^[A-Za-z0-9]{1,32}$, ou folder com o folder_id de uma pasta de mídia mfd_ existente, que reproduz diretamente os arquivos prontos dentro dela e nenhuma de suas subpastas. Não coloque media_id na própria primitiva nem envie itens resolvidos pelo servidor. Uma primitiva application fixa um release_id e uma primitiva iframe recebe um src e um title de 1 a 200 caracteres, então nenhuma delas aceita um seletor. src é qualquer página http ou https que a tela consiga alcançar, inclusive uma página da LAN ou atrás de um login; um link do YouTube é armazenado como seu embed com reprodução automática. src, e o fallback_src opcional de um iframe, podem trazer tokens de tela como {screen.field.kiosk_id}, e uma primitiva application pode trazer params com os mesmos tokens, de modo que uma playlist dá a cada tela sua própria página. Os Players Android, Amazon Signage Stick, Linux, Raspberry Pi e Windows abrem a própria página. O app web do Player e os Players macOS, Samsung Tizen, LG webOS e BrightSign a enquadram, então uma página que envia X-Frame-Options (DENY, SAMEORIGIN ou o obsoleto ALLOW-FROM), ou uma lista Content-Security-Policy frame-ancestors sem a origem do Player, mostra um quadro bloqueado neles, e o app web do Player mostra apenas páginas https sem login no endereço. Quando a publicação detecta uma página HTTPS pública que recusa enquadramento, a escrita ainda tem sucesso e a CLI imprime a entrada warnings do servidor: código iframe_framing_refused, o page_id, primitive_id e src, o cabeçalho que recusou e o próximo passo (use uma página que permita enquadramento a partir da origem do Player, ou peça ao seu responsável que permita essa origem). O servidor também acrescenta um aviso playlist.iframe_framing_refused ao registro de eventos, um por página que recusa, que events list imprime com primitive_id. Uma página da LAN, uma página http e uma página que o servidor não alcança em alguns segundos não são verificadas. Um Player informa uma playlist como em reprodução quando seu manifesto está na tela, então uma publicação verificada não prova que uma página iframe foi renderizada: aja sobre o aviso ou olhe a tela. As duas primitivas web exigem content_fit de fill, porque nenhuma delas tem tamanho intrínseco.

Um iframe também aceita reload_s (0, o padrão, nunca recarrega; de 60 a 86400 carrega src novamente a cada reload_s segundos enquanto a página está na tela), fallback_src (a página exibida quando src não carrega, com as formas e regras de src; um src recuperado a substitui na próxima recarga) e navigation_allowlist (de 1 a 64 fontes de host da forma [scheme://]host[:port][path], como example.com, *.example.com ou https://example.com/docs/; com uma lista, os links da página, as navegações por script e os redirecionamentos alcançam apenas src, fallback_src e endereços correspondentes; omita-o para não ter restrição, uma lista vazia é recusada). Um código de incorporação <iframe> colado é lido pelo seu src. Um link de compartilhamento do Google Slides, Docs ou Sheets, de Publicar na Web ou de incorporação, ou um link Incorporar do Microsoft 365, é armazenado reconstruído para a tela: os decks do Slides e do PowerPoint rodam em loop, um deck do Slides avança no próprio atraso do link, limitado à duração da página (dê à página o tempo do deck inteiro), e Docs, Sheets, Word e Excel recarregam a cada 5 minutos. Um arquivo que pede login aos espectadores é recusado com document_not_shared, cujo detalhe nomeia a configuração de compartilhamento a mudar. Veja Exibir uma página web, um vídeo ou um documento.

advance.mode é duration com after_ms, que em uma página com exatamente um vídeo do YouTube (nem playlist nem transmissão ao vivo) também pode levar until definido como video_end para que a página dure até o vídeo terminar e after_ms seja por quanto tempo ela é exibida quando a tela não consegue ler a duração do vídeo, media_end em uma página com exatamente uma primitiva de imagem ou vídeo, audio_end em uma página cujo audio_cue nomeia uma faixa sonora, ou application com max_ms quando o app termina sua própria vez chamando window.screenrig.nextPage(). Uma página application precisa de exatamente uma primitiva marcada controller; todo outro modo a proíbe. after_ms, max_ms e dwell_ms são milissegundos inteiros de 1.000 a 86.400.000, e uma imagem em uma página media_end precisa de dwell_ms. Uma página contém no máximo um stream e no máximo duas primitivas application ou iframe, e media_end proíbe ambos.

transition.type é um entre 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 ou stinger. duration_ms é obrigatório, de 0 a 60000. playlist init grava uma transição crossfade de 200 ms. Swipe move ambas as páginas juntas como um carrossel. Slide move a página que entra sobre a que sai, que se desloca um quarto da distância. Wipe revela a página que entra atrás de uma borda dura em movimento. Dip desvanece a página que sai para uma cor sólida e depois para a página que entra; color é um #RRGGBB opcional, padrão #000000, e válido apenas em dip. Os nomes das direções indicam o sentido do movimento: wipe-left é uma borda movendo-se para a esquerda. ease é opcional: linear, in, out ou in-out; o padrão é linear para crossfade e swipe-* e in-out para dip, wipe-* e slide-*; não é permitido em stinger. A página que entra controla sua transição. A primeira página de uma playlist não tem transição.

Um stinger é um gráfico temático em tela cheia que cobre a página de saída, troca pela página de entrada enquanto a tela está coberta, e então a descobre. Use-o para nomear uma seção de uma playlist: coloque-o na primeira página da seção. O objeto stinger é obrigatório para type: "stinger" e não permitido em outros tipos. Todos os seus membros são opcionais. theme é um dos neomustard (o padrão), cyanotype, propaganda, signal, avant-garde, bloom ou primetime, e corresponde aos temas dos cartões. title tem até 40 caracteres e subtitle até 60, definidos no tipo de exibição do tema. logo é media: mais o id de uma imagem pronta no projeto, por exemplo media:med_01EXAMPLE. accent é um #RRGGBB opcional que substitui o destaque do tema. duration_ms para um stinger é de 2000 a 6000 e cobre todo o bumper; durações típicas são de 2700 a 4000. O título permanece totalmente exibido por hang_ms, de 0 a 6000, padrão 1000 (um segundo), e hang_ms é no máximo 60% de duration_ms; um tempo maior requer um duration_ms maior. Um Player que não pode desenhar um stinger reproduz um crossfade da mesma duração. Veja a página ao vivo Cartão Stinger para assistir à transição.

O exemplo a seguir mostra uma transição de página stinger:

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

Um objeto enter opcional em uma primitiva adiciona uma animação de objeto: fade-up, fade-down, fade-left, fade-right, fade-in, zoom-in ou zoom-out, e um stagger opcional de 0 a 8 atrasa seu início em 120 ms por passo. Um motion opcional mantém uma primitiva em movimento depois que ela entra: spin e drift giram ou deslizam uma imagem ou um vídeo, e path move uma imagem, um vídeo, um aplicativo ou um iframe ao longo de waypoints. Veja Fundo e movimento da página.

Um objeto de página visibility opcional limita quando a página é exibida: um booleano enabled obrigatório, limites civis from e until opcionais, e até 16 windows recorrentes de dias e horários civis. from e until são YYYY-MM-DDTHH:MM no fuso horário de cada tela, from inclusivo e until exclusivo e posterior a from; uma janela é days (mon a sun) com start e end como HH:MM, informados juntos ou ambos omitidos para o dia inteiro, e um end igual ou anterior a start atravessa a meia-noite. enabled: false oculta a página; enabled: true precisa de pelo menos um de from, until, windows ou data. Cada playlist mantém pelo menos uma página sem campo visibility algum. Uma tela lê esses horários em seu fuso horário efetivo: a substituição, senão o fuso que seu Player informa, senão UTC.

Uma condição visibility.data de página, {key, path?, equals?}, mostra a página apenas enquanto um documento de dados de cartão corresponde: key é uma chave de dados de cartão ou um ID de cartão, path um ponteiro RFC 6901 dentro do documento, e equals uma string, um número, um booleano ou null (omita-o para testar se o valor existe). A chave {screen.weather} lê o clima da localização própria de cada tela, que screen update ID --location LAT,LON define: {"enabled":true,"data":{"key":"{screen.weather}","path":"/condition","equals":"rain"}} mostra a página apenas enquanto chove onde essa tela está. O documento do clima tem condition (clear, cloud, fog, rain, snow, storm ou wind), band (freezing abaixo de 0 °C, cold de 0 a 9, mild de 10 a 17, warm de 18 a 24, hot a partir de 25), temperatureC em graus inteiros e isDay. É o clima atual da célula de 0,25 grau da tela, atualizado cerca de uma vez por hora, não uma previsão. Uma tela sem localização nunca mostra a página, e a publicação recusa um path ou um equals que o documento não pode conter, como cloudy em vez de cloud. Um Player que não declara a capacidade de host page.conditions recebe essa página desativada. Condições de dados são um recurso do Plus: sem ele, uma gravação que adiciona uma condição visibility.data que a página ainda não tem recebe feature_not_in_plan, enquanto manter ou remover uma condição salva e a visibilidade por janelas de horário continuam liberadas. Mantenha uma página comum sem visibility como reserva.

Um primitivo video ou stream toca sem som, a menos que defina muted como false. Nesse caso, ele toca seu som no volume da tela enquanto sua página é a atual, e essa página pausa a trilha sonora da playlist, que retoma do mesmo ponto na próxima página sem som. Vários primitivos em uma mesma página tocam todos o seu som. Uma página com som não pode conter um audio_cue: uma gravação que adiciona um responde invalid_request em pages[i].audio_cue, “a page with sound cannot cue the soundtrack”, enquanto uma página antiga já armazenada que tem os dois continua tocando. Anúncios continuam sem som.

Um objeto audio opcional de nível superior adiciona uma trilha sonora que toca continuamente enquanto as páginas mudam e pausa em uma página com som. tracks lista de 1 a 128 entradas na ordem de reprodução, cada uma com um id único (o padrão de id da página) e o media_id de um objeto de mídia audio pronto. loop padrão é true e reinicia na primeira faixa após a última; volume padrão é 1 e varia de 0 a 1, multiplicado pelo volume do Player; cued padrão é false, e true para a trilha sonora após cada faixa para que uma faixa toque apenas quando uma página audio_cue a iniciar. Uma página comum pode conter audio_cue com um id track dessa lista e um booleano restart opcional (padrão false): quando a página aparece, o Player muda para essa faixa desde o início, reiniciando-a apenas quando já está tocando e restart é true. Cues são dicas, páginas de adslot não podem contê-las, e um cue sem trilha sonora é rejeitado. Uma página com advance {"mode":"audio_end"} termina quando a faixa que seu audio_cue nomeia termina, então requer esse cue e uma trilha sonora, não aceita after_ms, e segue as regras duration para primitivos de imagem e vídeo; um primitivo stream ainda precisa de uma página duration, e um aplicativo na página nunca é seu controlador; max_ms é uma dica opcional que o servidor substitui. playlist update substitui o documento inteiro, então omitir audio remove a trilha sonora; playlist patch a mantém, a menos que audio seja fornecido, e --clear-audio ou audio: null a remove. Uma faixa não tem trilha sonora. Criação de trilha sonora.