Telas: comandos da CLI

Pareie um Player com o código exibido na tela dele.

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

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

A resposta traz public_url e a screen pareada. O Player conclui o pareamento na próxima vez que contatar o serviço, sem nada a fazer no display: screen show informa state active e online true quando isso acontece. Após uma solicitação interrompida, execute novamente o comando idêntico para reutilizar a chave de idempotência salva.

Concluir a configuração de um Player de navegador a partir do código que ele exibe.

browser setup --code CODE [--open]

screenrig browser setup --code SETUP_CODE --open

A resposta traz code, status (claimed), screen_id e player_public_url da tela. O CLI retém uma URL que falha nas verificações de segurança, com o aviso player_url_withheld. Um código inválido ou expirado não cria nenhuma tela. Após uma solicitação interrompida, execute novamente o comando idêntico.

Listar telas. Telas arquivadas são omitidas, a menos que você as solicite.

screen list [--state archived] [--tag TAG] [--folder ID|root] [--field NAME=VALUE...] [--near LAT,LON,KM]

screenrig screen list --tag Lobby
screenrig screen list --folder sfd_01EXAMPLEFOLDER000000000
screenrig screen list --field region=north
screenrig screen list --near 47.6062,-122.3321,25

Os filtros se combinam. Cada linha traz tags, folder_id, fields e location da tela, quando houver. Com --human, a tabela só adiciona uma coluna quando uma tela listada tem o valor: PLATFORM, REASON (o archive_reason de uma tela arquivada), TAGS, FOLDER, FIELDS, LOCATION, ASSIGNED (uma tela que reproduz algo diferente de sua playlist padrão), HEALTH (uma tela que precisa de atenção) e UPGRADE (uma tela cujo Player ainda está passando para a versão da playlist emitida, ou falhou ao fazê-lo). --state archived também lista telas que um Player arquivou por conta própria (device_reset, device_unpair) e telas que screen replace arquivou (replaced).

Leia uma tela, incluindo revisão, atribuição e estado online.

screen show <id>

screenrig screen show scr_01EXAMPLESCREEN00000000

tags lista as tags da frota da tela. effective_playlist, takeover e playlist_schedule reportam o que a tela reproduz e por quê; veja Programações e takeover. health e as capacidades do host do Player estão em Saúde e energia do dispositivo. online é verdadeiro enquanto um Player está conectado, incluindo uma breve janela de reconexão. last_online_at e last_ip opcionais aparecem após a primeira conexão. observation opcional reporta as superfícies que um Player pintou: id, width, height, pixel_ratio e presentation. Todos são somente leitura; screen update não pode enviá-los, e uma tela arquivada ainda retorna sua linha.

commands lista os últimos 10 reinícios, recarregamentos, limpezas de cache, reinícios do app e atualizações da tela, do mais antigo para o mais recente, cada um com seu type, seu state (queued, sent, done, failed, expired, cancelled ou superseded), seu source (schedule para um reinício emitido por uma programação de reinício; ausente para um pedido por uma pessoa), seu expires_at e quando foi enviado ou concluído. reboot_schedule e next_reboot_at informam a programação de reinício da tela e o início de sua próxima janela de reinício. Uma limpeza de cache, reinício do app ou atualização que o Player finalizou também traz seu cause e um detail curto, que --human imprime como uma coluna CAUSE e uma linha abaixo da tabela. suspension traz o message e o since de uma tela suspensa. Uma tela arquivada por screen replace informa replaced_by, a tela para a qual seu dispositivo foi movido. Com --human, screen show imprime cada um deles.

last_outage informa a última queda da tela: offline_since, back_at e duration_s e, quando um relatório de saúde a determina, uma likely_cause entre device_restart, app_crash, app_restart, network ou platform; ela está ausente quando o screenRIG não consegue determiná-la. Uma reinicialização é decidida quando a tela volta, enquanto uma causa de rede ou do screenRIG espera o próximo relatório de saúde do Player, que pode levar até quinze minutos. glass traz os veredictos que o screenRIG tirou dos relatórios de reprodução e das capturas de tela. Com --human, screen show imprime Last outage e Likely cause, e Playlist stalled, Blank screen ou Frozen picture para um veredicto que encontrou um problema; Notificações diz o que os veredictos deixam de fora.

folder_id nomeia a pasta da tela e está ausente na raiz do projeto. fields, location e wall aparecem depois de definidos: veja screen update e screen wall set. Cada entrada de observation.surfaces também traz rotation quando o Player consegue lê-lo, e um videowall informa uma entrada por saída, com os nomes que screen wall set aceita.

manifest_upgrade informa se o Player passou para a versão da playlist emitida para ele. Seu state é none, pending, downloading, preparing, activating, retrying, failed, blocked, partial ou current, ao lado de desired_playlist e active_playlist (id, name e revision), a última versão que o Player confirmou, o que não prova que todas as sessões a exibem. Uma atualização com falha ou parcial também traz code, attempt, retry_at e missing_page_count. --human imprime Target v42 · Playing v41. Uma atualização com falha não agenda nova tentativa: corrija a causa e depois execute screen reload ou atribua a playlist novamente. Uma atribuição salva não confirma a reprodução.

applications_unsupported aparece enquanto o Player pareado não consegue exibir páginas application ou iframe: o manifesto não muda e o Player as ignora. recovery_pending aparece enquanto um display que perdeu sua identidade armazenada se oferece para reconectar como esta tela, com expires_at da oferta e os valores platform, model, firmware e manufacturer que o display informa: veja screen recover.

Alterar o nome, a atribuição de playlist, a substituição de fuso horário, os campos ou a localização de uma tela em uma só chamada.

screen update <id> [--name NAME] [--playlist-id ID | --clear-playlist] [--timezone ZONE | --clear-timezone] [--field NAME=VALUE...] [--unset-field NAME...] [--clear-fields] [--location LAT,LON [--location-name NAME] [--address TEXT] | --clear-location] [--expect-rev REVISION]

Informe pelo menos um entre --name, --playlist-id, --clear-playlist, --timezone, --clear-timezone, --field, --unset-field, --clear-fields, --location ou --clear-location.

screenrig screen update scr_01EXAMPLESCREEN00000000 --name "Lobby"
screenrig screen update scr_01EXAMPLESCREEN00000000 --field store_number=0142 --field region=north
screenrig screen update scr_01EXAMPLESCREEN00000000 --location 47.6062,-122.3321 --location-name "Seattle HQ"
screenrig screen update scr_01EXAMPLESCREEN00000000 --clear-playlist --expect-rev 3

Em revisão, uma alteração apenas de --playlist-id é proposta como screen assign; uma sessão Propor não pode alterar outros campos.

Alterar campos ou localização muda a revisão do manifesto da tela, então uma tela que exibe uma playlist assume os novos valores. Cartões e páginas iframe os leem por tela, então uma única playlist mostra os valores próprios de cada tela: {screen.field.NAME}, {screen.name} e {screen.timezone} preenchem qualquer parâmetro de texto de um cartão, "location": "{screen.location}" preenche a localização de um cartão no formato que esse cartão aceita, e uma chave de dados do cartão pode conter {screen.field.NAME}, como menu-{screen.field.store_number}. Uma tela sem um campo mostra esse texto vazio, e o cartão fica sem essa chave de dados ou localização. screen show lista os campos e a localização de uma tela, e screen list encontra telas por eles. Veja Tokens de tela em endereços de iframe e parâmetros de aplicativo.

Criar uma nova playlist a partir de um arquivo preparado e atribuí-la a uma tela.

screen publish <id> <file> [--expect-rev REVISION] [--note TEXT] [--no-wait] [--poll-ms MS] [--timeout MS] [--no-progress]

screenrig screen publish scr_LOBBY lobby.json

Isto cria uma nova playlist e a atribui. Não atualiza uma playlist existente pelo nome. Inspecione primeiro o documento preparado. Repita a entrada idêntica para retomar uma falha ambígua. A leitura da atribuição não prova a reprodução; solicite uma captura de tela separadamente. Em revisão, retorna stage: pending_review com ambas as revisões. Veja Preparar, publicar e editar playlists.

Após a atribuição, o comando espera até o Player exibir a playlist: data.stage é playing e data.playback_verified é true. As mudanças de etapa são impressas no stderr conforme acontecem, como linhas JSON ou, com --human, como texto. Repetir o comando idêntico depois que uma publicação terminou informa essa publicação (data.already_published) enquanto a tela ainda exibe a playlist, e publica de novo quando a tela já passou para outra coisa.

Aponte uma tela, ou uma frota de telas, para uma playlist.

screen assign (<id>... | --tag TAG | --folder ID) --playlist-id ID [--expect-rev REVISION] [--note TEXT]

screenrig screen assign scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen assign --folder sfd_01EXAMPLEFOLDER000000000 --playlist-id pl_01EXAMPLEPLAYLIST000000

Uma playlist que programa páginas pode ser atribuída a qualquer tela: as programações são lidas no fuso horário próprio da tela (sua substituição, senão o fuso que seu dispositivo informa, senão UTC).

Para publicar em uma frota, crie a playlist uma vez com playlist create, depois execute screen assign --tag TAG --playlist-id ID. screen publish direciona uma tela.

Sob acesso Propor, ou em um projeto que exige revisão para alterações de agentes, a alteração em uma tela ou em toda a frota responde pending_review em vez disso: data.review traz o ID da revisão e seu url no dashboard, um aviso pending_review nomeia a URL, e data.next é reviews show ID. Nada muda na tela até uma pessoa aprovar, então não repita a escrita. Em uma tela em uma pasta protegida isso responde pending_review em qualquer nível de acesso, e um aprovador diferente de você e da pessoa para quem você trabalha decide (senão, second_approver_required, saída 3). Um chamador limitado a pastas de telas atribui apenas em telas do seu escopo. Uma atribuição salva não confirma a reprodução; screen screenshot mostra o que está na tela.

Substitui o fuso horário em que as regras civis de uma tela são lidas, ou remove a substituição.

screen set-timezone <id> (--timezone ZONE | --clear) [--expect-rev REVISION]

screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --timezone America/Los_Angeles
screenrig screen set-timezone scr_01EXAMPLESCREEN00000000 --clear

Toda tela tem um fuso horário efetivo, e toda regra civil o lê: visibilidade de página, slots de anúncio, programações de playlist, takeovers, campanhas, programações de display e de reinício, e {screen.timezone}. É esta substituição, senão o fuso que o Player da tela informa a partir do seu dispositivo, senão UTC. Uma tela não precisa de substituição enquanto seu dispositivo informa o fuso correto. screen show imprime o fuso efetivo como Timezone com sua origem, effective_timezone e timezone_source (screen, device ou default) em --json. Alterar o fuso efetivo reemite a revisão do manifesto.

ZONE é Area/City, como America/New_York ou Asia/Tokyo, ou UTC.

Definir o videowall de uma tela: um Player controlando de dois a doze displays como um único canvas.

screen wall set <id> --outputs NAMES --arrangement row|column|grid [--columns N] [--rotation 0|90|180|270] [--expect-rev REVISION]

screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs HDMI-A-1,HDMI-A-2 --arrangement row
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3 --arrangement row --rotation 90 --expect-rev 4
screenrig screen wall set scr_01EXAMPLESCREEN00000000 --outputs DP-1,DP-2,DP-3,DP-4,DP-5,DP-6 --arrangement grid --columns 3

Um Player controla os displays como um único videowall, então uma página da playlist se estende por todos eles. A definição substitui o videowall inteiro, então repita --rotation e --columns para mantê-los. Apenas a instalação em quiosque do Player para Linux e o Player para Windows declaram a capacidade display.wall; qualquer outro Player responde wall_unsupported (saída 5) e nada muda. O acesso Propor não pode alterar um videowall (insufficient_access). Uma wall de 2 ou 3 telas exige o Plus ou superior, e uma de 4 a 12 telas, o Enterprise: um plano sem ela responde feature_not_in_plan (saída 8), enquanto screen wall clear e uma definição que mantém a wall salva continuam liberados. Veja Videowalls.

Crie a playlist para o formato do videowall com playlist init e o ID da tela, o que grava o canvas correspondente e format (displays, arrangement, orientation e columns para uma grade). Os displays de um primitivo, como [2] ou [1, 2, 5, 6], indicam os números de display que ele cobre, contados a partir de 1 da esquerda para a direita e depois de cima para baixo, e devem preencher um retângulo do videowall. Atribuir uma playlist cujo formato não é o do videowall resulta em playlist_format_mismatch (saída 5); uma playlist sem formato é reproduzida igual em todos os displays. Quando a tela reproduz uma playlist com formato correspondente, cada display mostra seu número e nome por 20 segundos após uma mudança, para você conferir a ordem na tela.

Remover o videowall de uma tela.

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

screenrig screen wall clear scr_01EXAMPLESCREEN00000000

A playlist atribuída não é verificada de novo: se ela tem um format, o manifesto da tela é degradado (wall_format_mismatch) e o Player mantém a última página válida até você atribuir uma playlist sem formato. Uma tela sem videowall responde sem alteração. O acesso Propor não pode alterar um videowall (insufficient_access).

Ocultar uma tela e escurecer seu vidro.

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

screenrig screen archive scr_01EXAMPLESCREEN00000000

Arquivar oculta a tela da listagem padrão e escurece o vidro. Não desvincula o Player.

Quem tem a chave do display ainda pode se conectar enquanto a tela está arquivada. Para aposentar o hardware de vez, deixe a tela arquivada ou mova a tela para um novo hardware com screen recover ou screen replace, que desativam a chave antiga.

Restaure uma tela arquivada para a listagem padrão.

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

screenrig screen unarchive scr_01EXAMPLESCREEN00000000

Um Player também pode arquivar sua própria tela: um reset confirmado em um Player que mantém uma chave, ou desparear um Player de navegador pareado por cookie. screen show então reporta archive_reason como device_reset ou device_unpair (project para um arquivo que você solicitou), com archived_at. A tela mantém sua vinculação de dispositivo por todos os motivos, então um Player que ainda mantém essa chave ou cookie de dispositivo permanece escuro e retoma na desarquivação sem novo pareamento. O Player que foi resetado ou despareado descarta sua chave ou cookie e pareia novamente como uma nova tela. Uma chave substituída por uma recuperação de tela confirmada permanece aposentada.

Uma tela arquivada como replaced por screen replace não mantém vinculação de dispositivo, então desarquivar recusa essa tela e screen delete a remove.

Mostrar um aviso em uma tela no lugar do conteúdo dela, até que seja retomada.

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

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

Uma tela suspensa mostra a mensagem no lugar do conteúdo dela. Nada mais muda: sua playlist, programação, takeover e controle de exibição permanecem e continuam evoluindo, e screen resume mostra o que a tela estaria mostrando agora. screen show reporta suspension com o message e o since; suspender uma tela já suspensa substitui a mensagem e mantém since. Suspender aumenta a revisão da tela, e o Player busca novamente de imediato. Uma tela arquivada responde screen_archived.

Encerrar a suspensão de uma tela para que ela volte a mostrar seu próprio conteúdo.

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

screenrig screen resume scr_01EXAMPLESCREEN00000000

Retomar volta a mostrar o conteúdo próprio da tela, a partir do que a tela estaria mostrando agora, e o Player busca novamente de imediato. Uma tela que não está suspensa responde inalterada, sem mudança de revisão. Uma tela arquivada responde screen_archived.

Excluir uma tela.

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

screenrig screen delete scr_01EXAMPLESCREEN00000000

Excluir remove uma tela apenas enquanto nenhuma chave de Player estiver vinculada a ela, e screen show reporta deletable: true para essa tela. Um Player que pareia por código, seja nativo ou de navegador, mantém uma chave, e a chave permanece vinculada à sua tela, então excluir essa tela responde 409 screen_archive_required (código de saída 5): arquive-a em vez disso. Somente um Player de navegador pareado por cookie não mantém chave, e sua tela pode ser excluída esteja pareada ou ainda pendente.

Para parear como uma nova tela um display que já tem uma chave, confirme uma redefinição no próprio Player e depois resgate o código que ele mostra com screen pair; a tela antiga permanece arquivada. Para mover uma tela para um hardware substituto, use screen recover, ou screen replace quando esse hardware já estiver pareado como uma tela própria.

Reconectar um display que perdeu sua identidade armazenada à tela como a qual ele foi pareado.

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

screenrig screen show scr_01EXAMPLESCREEN00000000
screenrig screen recover scr_01EXAMPLESCREEN00000000

Um display que perdeu sua identidade armazenada e agora informa os identificadores de hardware desta tela durante o pareamento faz uma oferta. screen show a informa como recovery_pending, com seu prazo e, quando o display informa, platform, model, firmware e manufacturer. Nada é revinculado até este comando confirmar: a tela mantém seu rótulo, playlist, fuso horário, programações e histórico, e a nova chave do display substitui a anterior, que é desativada após um período de tolerância de quinze minutos. Uma tela arquivada por uma redefinição do dispositivo permanece arquivada até screen unarchive.

Compare o modelo e o firmware informados com o display que você espera antes de confirmar: qualquer aplicativo em execução em um display pode ler seus identificadores, então a oferta sozinha não prova qual display está pedindo. O serviço recusa uma oferta enquanto o Player atual da tela ainda está online, e uma tela aceita no máximo três ofertas por hora. Sem uma oferta, o comando responde recovery_not_offered, uma oferta cuja sessão de pareamento expirou responde recovery_expired, e identificadores associados a mais de uma tela respondem recovery_ambiguous; nada é revinculado. A recuperação nunca atravessa projetos.

Mover para esta tela o dispositivo pareado como outra tela, mantendo as configurações e o histórico desta tela.

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

screenrig screen replace scr_01EXAMPLESCREEN00000000 --with scr_01EXAMPLENEWSCREEN000000

Pareie primeiro o novo hardware como sua própria tela e depois substitua. A chave do dispositivo, ou a credencial de um Player de navegador, agora dá acesso a <id>, que mantém seu nome, tags, fuso horário, playlist, programações, takeover, programação e substituição de exibição, video wall, comentários, campos, localização e histórico, e assume o host e o Player da tela substituta. Sua saúde, status, armazenamento e comandos na fila recomeçam do zero. A tela indicada em --with é arquivada com archive_reason replaced e replaced_by apontando para <id>. Ela não mantém vinculação de dispositivo, então screen unarchive não pode restaurá-la e screen delete a remove. A chave que <id> mantinha é aposentada após uma janela de tolerância de quinze minutos; depois disso, o dispositivo antigo é recusado. Ambas as telas devem estar ativas e ter um Player pareado: uma tela que ainda aguarda pareamento responde resource_conflict, uma arquivada responde screen_archived, e um video wall precisa de um Player substituto que declare display.wall (wall_unsupported). O pedido sempre traz uma chave de idempotência, e uma nova tentativa exata retorna a resposta original.

Para mover um display que perdeu sua identidade armazenada e agora informa os identificadores desta tela, use screen recover.

Emitir um novo ID público para uma tela.

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

screenrig screen rotate-public-id scr_01EXAMPLESCREEN00000000

O public_id da tela, a credencial em sua URL pública, é substituído e toda sessão aberta com o valor antigo termina. O pareamento do Player é mantido: um Player pareado abre uma nova sessão e continua exibindo seu conteúdo.

Criar o link de uma tela, ou substituí-lo, e imprimir sua URL do Player.

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

screenrig screen link create scr_01EXAMPLESCREEN00000000

Imprime data.url, a URL do Player (https://play.screenrig.ai/player/#screen=…) para colar como URL de uma fonte de navegador no vMix ou no OBS, que não guarda armazenamento e, de outro modo, perderia o pareamento a cada carregamento. O Player roda a partir da URL a cada carregamento: a URL é todo o pareamento. Criar o link de novo o substitui (data.replaced é true): a URL antiga para de funcionar imediatamente e o Player aberto a partir dela mostra um aviso sem conteúdo. A URL é uma credencial que abre a tela: é impressa sob um rótulo sensível, mantida fora do log de operação e exibida de novo por screen link show. Abra-a em um único lugar. Uma tela que não foi pareada responde resource_conflict (código de saída 5), e uma tela arquivada responde screen_archived. Após uma requisição interrompida, execute de novo o mesmo comando: ele reutiliza a chave de idempotência salva e retorna o mesmo link.

Imprimir o link de uma tela e sua URL do Player.

screen link show <id>

screenrig screen link show scr_01EXAMPLESCREEN00000000

Imprime data.url sob um rótulo sensível com data.hint (os quatro últimos caracteres do segredo), data.created_at e data.last_used_at depois que um Player abre o link. Uma credencial somente leitura recebe url vazio com url_redacted true, e a saída humana informa que a URL foi retida; um login Manage a recebe. Uma tela sem link responde screen_link_not_found (código de saída 4) e nomeia o comando que cria um. screen show imprime Screen link: on (…HINT) para uma tela que tem um, e nunca sua URL.

Desativar o link de uma tela.

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

screenrig screen link delete scr_01EXAMPLESCREEN00000000

A URL para de funcionar imediatamente e toda sessão que ela abriu termina: uma fonte de navegador que ainda a exibe mostra um aviso e nenhum conteúdo até receber uma nova URL. A tela, seu pareamento e seu conteúdo não são alterados. Tem sucesso, sem alterar nada, quando a tela não tem link.

Peça ao Player de uma tela, ou a todos os Players de uma frota, para recarregar uma vez.

screen reload (<id>... | --tag TAG | --folder ID) [--expires-in DURATION] [--expect-rev REVISION]

screenrig screen reload scr_01EXAMPLESCREEN00000000
screenrig screen reload scr_01EXAMPLESCREEN00000000 --expires-in 2h
screenrig screen reload --tag Lobby
screenrig screen reload --folder sfd_01EXAMPLEFOLDER000000000

A resposta traz um reload_id, um state e um expires_at. Uma tela online recebe o recarregamento imediatamente (state sent); uma tela offline o mantém como queued e o recebe quando fica online antes de expires_at, 24 horas após o pedido, a menos que --expires-in diga o contrário. Um recarregamento mais recente substitui um que ainda está na fila; screen show lista os commands da tela e screen command cancel cancela um que ainda está na fila. Em uma frota, o reload de cada resultado traz o mesmo state. Um Player web recarrega na próxima troca de página; um Player nativo reconecta, refaz o manifesto e verifica atualizações. Um Player ignora um recarregamento dentro de dez minutos do último que executou. Recarregar funciona em telas ativas e arquivadas e não altera a revisão da tela.

Publique uma mensagem transitória como chrome de palco em uma tela ao vivo ou em uma frota.

screen toast (<id>... | --tag TAG | --folder ID) --text TEXT [--level info|alert|error] [--duration-ms MS]

screenrig screen toast scr_01EXAMPLESCREEN00000000 --text "Lobby closed"
screenrig screen toast --tag Lobby --text "Closing in ten minutes"
screenrig screen toast --folder sfd_01EXAMPLEFOLDER000000000 --text "Closing in ten minutes"

Um toast não é um primitivo: não ocupa slot de canvas, não tem camada, e não participa de prontidão ou crossfade. O último vence, não há fila nem cancelamento, e o envelope aceito é só { expires_at }. Nunca coloque credenciais ou outro material secreto no texto.

Mostrar o nome de uma tela sobre o conteúdo dela por um tempo, para encontrá-la no local.

screen identify <id> [--duration DURATION]

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

O Player desenha uma sobreposição em tela cheia sobre seu conteúdo, com o nome da tela bem grande e o id dela pequeno logo abaixo. A reprodução continua por baixo, e uma identificação mais recente substitui a sobreposição. O envelope aceito traz identify_id, duration_ms e um expires_at 60 segundos após o pedido, de modo que uma tela offline nunca a mostra depois. Somente um Player que declara a capacidade identify mostra a sobreposição: qualquer outra tela responde 409 identify_unsupported (código de saída 5) e nada é enviado; atualize o Player ou mostre o nome com screen toast. Uma tela arquivada responde screen_archived e uma tela que ainda aguarda pareamento responde resource_conflict. Identificar não altera a revisão da tela.

Iniciar uma página da playlist que uma tela está reproduzindo agora, para verificar essa página com uma captura de tela.

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

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

A página começa do início no Player da tela e a rotação continua a partir dali, então uma captura de tela feita em seguida mostra essa página sem esperar a rotação. A página deve pertencer à playlist que a tela reproduz agora: seu takeover; senão, uma campanha vigente; senão, sua programação; senão, sua playlist atribuída. Qualquer outra página responde page_not_on_screen (saída 5), e o problema nomeia essa playlist. Um Player que não declara a capacidade play_page em seu relatório de host responde play_page_unsupported (saída 5) e nada é enviado: atualize o Player.

A resposta traz playlist_id, page_id, manifest_revision e expires_at. A solicitação expira após 60 segundos e não altera a revisão da tela. Uma tela arquivada responde screen_archived e uma tela que ainda aguarda o pareamento responde resource_conflict. Uma nova tentativa com a mesma chave de idempotência repete a resposta original.

Capture uma imagem estática de uma tela ativa, ou de todas as telas de uma frota, e grave no disco.

screen screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
screen screenshot (<id> <id>... | --tag TAG | --folder ID) [--output DIRECTORY] [--concurrency N] [--timeout MS] [--poll-ms MS]

screenrig screen screenshot scr_01EXAMPLESCREEN00000000 --output ./lobby.webp

screenrig screen screenshot --tag Lobby --output ./lobby-shots

screenrig screen screenshot --folder sfd_01EXAMPLEFOLDER000000000 --output ./north-shots

O comando bloqueia até o WebP estar no disco. O envelope informa screen_id, capture_id, path, bytes, sha256, width e height, e nunca bytes de imagem. O último vence: uma solicitação posterior substitui uma captura em andamento. Uma captura de tela do Player web desenha cada página iframe como um bloco cinza-escuro com o rótulo "Embedded web page" e cada aplicativo como ele mesmo se renderiza; a imagem não traz marcador para o bloco, então não prova que uma página iframe foi renderizada.

Com vários IDs, --tag ou --folder, a resposta é um resultado de frota com action: "screenshot", o selector e o diretório output; cada resultado ok traz path, bytes, sha256, width e height. Com --tag, a CLI primeiro lista as telas com tag, seguindo cada página da lista; cada página da lista é uma solicitação de agente e as capturas em si não são contadas, e vários IDs não precisam de lista. --idempotency-key é recusado nesta forma, porque cada captura usa a própria chave. Se uma captura falhar de forma inesperada, o resultado dessa tela é unexpected_error, nenhuma captura nova começa, as telas que ainda esperam relatam not_attempted e o código de saída é 1.

Para uma tela, o envelope também traz frame.flat, que indica se esta imagem é de um único tom uniforme, e picture, o veredito de tela em branco ou congelada quando existe. Uma imagem uniforme sozinha não é um veredito: uma transição entre páginas, ou uma página preta de propósito, parece igual. Com --folder, o CLI lista a pasta e cada pasta dentro dela, um screen list --folder por pasta, e uma tela que a lista mostra offline é informada como falha sem captura.

O servidor admite 10 capturas por tela, 30 por organização e 30 por endereço, por minuto; o CLI tenta de novo as respostas 429 e 5xx com backoff e respeita Retry-After. Uma captura que não pode ser concluída é screenshot_unavailable (saída 5): a tela está offline, a solicitação timed_out, a página exibida contém uma superfície que o Player não consegue capturar (unsupported_surface, como um iframe de terceiros visível no Player de navegador), a captura do Player falhou (capture_failed) ou a captura ainda estava pendente quando --timeout acabou. --timeout 0 deixa a espera por conta do servidor, que expira uma solicitação sem resposta após 30 segundos. Uma captura com falha traz error.display quando o Player informou seu display: power, connected, reported_at e stale (após 35 minutos). Um relatório recente com off ou standby sugere tentar de novo quando o display estiver ligado.

Iniciar a visualização ao vivo de uma tela, ou renová-la, e imprimir a página do dashboard que a mostra.

screen live start <id> [--duration DURATION] [--wait DURATION]

screenrig screen live start scr_01EXAMPLESCREEN00000000
screenrig screen live start scr_01EXAMPLESCREEN00000000 --duration 2m --wait 60s

A visualização ao vivo mostra no dashboard o que uma tela reproduz, em vídeo; o CLI inicia, lê e encerra a sessão e nunca transporta o vídeo. data é a sessão com viewer_url, a página a abrir. Iniciar uma tela que já tem uma sessão a renova: a concessão passa a ser o mais tardio entre seu fim atual e --duration a partir de agora, nunca além de cinco minutos depois do início da sessão. Depois a sessão termina sozinha: nada a renova nem a reinicia, e a próxima sessão exige um novo screen live start. Ela termina antes quando a concessão vence, quando screen live stop é executado ou quando o Player a encerra.

O comando pede ao Player que publique e lê a sessão a cada segundo por até --wait, até o Player informar que está conectado. Se o Player não tiver conectado quando a espera acabar, a resposta ainda é ok, com o aviso live_not_ready: leia screen live status novamente ou abra viewer_url. Uma sessão que terminou durante a espera é live_unavailable (saída 5) e seu detalhe nomeia ended_reason, como consent_timeout (no Android, alguém na tela permite a captura da tela uma vez a cada início do Player). Uma tela offline também é live_unavailable, e uma tela arquivada responde screen_archived. Um Player que não declara a capacidade live_view responde live_unsupported (saída 5) e nada é enviado: atualize o Player. Um servidor sem relay de mídia responde feature_unavailable: use screen screenshot. A visualização ao vivo é gratuita. Veja Visualização ao vivo.

Ler a sessão de visualização ao vivo de uma tela.

screen live status <id>

screenrig screen live status scr_01EXAMPLESCREEN00000000

state é idle (sem sessão), requested (o Player foi solicitado), publishing (o relay mantém o vídeo dela) ou ended, com ended_reason por dez minutos. publisher.connected é o relatório do próprio Player, com no máximo 45 segundos, e não prova que há imagem. data inclui viewer_url.

Encerrar a sessão de visualização ao vivo de uma tela.

screen live stop <id>

screenrig screen live stop scr_01EXAMPLESCREEN00000000

Encerra a sessão e diz ao Player para parar de publicar, depois imprime a sessão como está: ended com ended_reason stopped. Tem sucesso quando não há sessão. Uma sessão também termina sozinha quando sua concessão vence.

Salvar quadros JPEG do que uma tela reproduz, a partir de seu stream ao vivo, para verificar a reprodução e o movimento.

screen live frame <id> [--output PATH] [--count N] [--interval DURATION] [--duration DURATION] [--wait DURATION] [--stop]

screenrig screen live frame scr_01EXAMPLESCREEN00000000
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output now.jpg --stop
screenrig screen live frame scr_01EXAMPLESCREEN00000000 --output frames/ --count 5 --interval 1s

O comando inicia a sessão ao vivo, espera o Player publicar, pede quadros ao relay de mídia e lê cada novo quadro uma vez. Um quadro é o vídeo como o encoder do Player o enviou, reduzido a no máximo 1280x720 e com perdas, cerca de um por segundo: ele mostra movimento e o que está na tela agora, então compare quadros (--count 5 --interval 1s) para verificar se o conteúdo se move. Não é uma captura de tela, que continua sendo a prova do layout. Os quadros são gratuitos.

data é {screen_id, live_id, frames}, com path, captured_at, width, height, bytes e sha256 por quadro, e stopped true quando --stop encerrou a sessão. Sem --stop, a sessão fica por conta da sua concessão. Um Player que não publica dentro de --wait, ou que não envia nenhum quadro novo dentro desse prazo, é live_not_ready (saída 5); no Android, alguém na tela permite a captura da tela uma vez a cada início do Player. Uma sessão que terminou, ou cujos quadros pararam de chegar, é live_unavailable (saída 5). Um Player sem a capacidade live_view responde live_unsupported, e um servidor sem relay de mídia ou sem quadros responde feature_unavailable (saída 4): use screen screenshot.

Definir, adicionar, remover ou limpar as tags em uma tela ou frota.

screen tag (<id>... | --tag TAG | --folder ID) (--set TAGS | --add TAGS | --remove TAGS | --clear) [--expect-rev REVISION]

screenrig screen tag scr_01EXAMPLESCREEN00000000 --set Lobby,Floor2
screenrig screen tag scr_01EXAMPLESCREEN00000000 --add Spring
screenrig screen tag --tag Lobby --add Spring
screenrig screen tag --folder sfd_01EXAMPLEFOLDER000000000 --add Spring

Uma tag tem de 1 a 32 letras ou dígitos, e uma tela carrega no máximo 16 tags únicas. Tags selecionam frotas; nunca são autorização e nunca chegam ao Player. Mudar tags atualiza a revisão da tela, não a do manifesto. Para uma tela o envelope é a tela atualizada. --add e --remove leem a tela primeiro e escrevem o novo conjunto protegido por --expect-rev ou a revisão recém-lida, então uma mudança concorrente retorna revision_conflict (exit 6) ao invés de ser sobrescrita; execute o comando novamente. Em uma frota, --add e --remove aplicam-se atomica e individualmente ao conjunto armazenado de cada tela, e uma tela que ultrapassaria 16 tags falha em seu próprio resultado com invalid_request.

Sempre que as tags mudam (screen tag, uma atualização de tela pela API, o editor de tags do painel), o levels da resposta lista, em gained e lost, as campanhas cujo público de tag a tela passou a integrar ou deixou, cada uma com seu source (campaign), id, a contagem de screens e, quando a campanha tem alcance, reach_before e reach_after. Um screen tag da frota os soma em toda a frota. Leia levels.lost antes de chamar uma edição de tag de inofensiva: remover a última tag correspondente das telas de uma campanha esvazia esse grupo e dispara as notificações reach_dropped e group_empty.

Mover telas e pastas de telas para uma pasta de telas, ou de volta para a raiz do projeto.

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

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

A movimentação é uma única solicitação de tudo ou nada. Uma pasta se move com tudo o que há dentro dela e não pode ser movida para dentro de si mesma nem de uma pasta dentro dela; as pastas se aninham em no máximo 10 níveis. Os itens que já estão no destino ficam como estão e não são contados. data.screens e data.folders contam o que foi movido. data.levels lista, em gained e lost, as campanhas em cujo público de pasta as telas movidas entraram ou saíram (source campaign, com reach_before e reach_after) e as playlists padrão de pasta que elas passaram ou deixaram de exibir (source folder). As telas reavaliam sua playlist em cerca de 15 segundos; screen show informa effective_playlist e campaign explain SCREEN_ID diz por quê.

Um chamador limitado a pastas de telas move apenas telas e pastas dentro do seu escopo para uma pasta dentro dele; qualquer outra coisa, inclusive a raiz do projeto, recusa a movimentação inteira com outside_screen_scope (saída 3). Uma movimentação para dentro ou para fora de uma pasta protegida responde pending_review com uma revisão protected_change que um segundo aprovador decide, então não repita a escrita; --note diz ao aprovador o motivo. Após uma solicitação interrompida, execute novamente o comando idêntico para reutilizar a chave de idempotência salva.

Listar as pastas de telas do projeto como uma árvore, com as telas ativas diretamente em cada uma e sua playlist padrão.

screen folder list

screenrig screen folder list

Retorna todas as pastas de telas do projeto, no máximo 1000, ordenadas por nome. data.items traz de cada pasta: id, name, parent_id (null na raiz do projeto), default_playlist_id quando definido, protected quando definido, screens (as telas ativas diretamente dentro, não as das pastas abaixo) e revision. Com --human, a saída é a árvore, uma linha por pasta com seu caminho. A pasta de uma tela é folder_id em screen list e screen show, ausente na raiz do projeto. Acesso somente leitura é suficiente.

Inspecionar uma pasta de telas.

screen folder show <id>

screenrig screen folder show sfd_01EXAMPLEFOLDER000000000

Retorna uma pasta com os campos que screen folder list retorna. Acesso somente leitura é suficiente.

Criar uma pasta de telas na raiz do projeto ou dentro de outra pasta.

screen folder create --name NAME [--parent ID] [--default-playlist-id ID] [--note TEXT]

screenrig screen folder create --name "North Tower"
screenrig screen folder create --name "Level 2" --parent sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000

Uma organização tem no máximo 1000 pastas em seus projetos (quota_exceeded), aninhadas em no máximo 10 níveis (invalid_request). Coloque telas nelas com screen move. Uma pasta passa então a ser o alvo de suas telas nos comandos de frota e como público de campanha: veja Pastas de telas.

Um chamador limitado a pastas de telas só cria pastas dentro do seu escopo: --parent deve ser uma pasta dele (outside_screen_scope, saída 3). Uma pasta criada dentro de uma pasta protegida responde pending_review com uma revisão protected_change que um aprovador diferente de você e da pessoa para quem você trabalha decide, então não repita a escrita; --note diz ao aprovador o motivo. Após uma solicitação interrompida, execute novamente o comando idêntico para reutilizar a chave de idempotência salva.

Renomear uma pasta de telas, movê-la com tudo o que há dentro, ou definir ou limpar sua playlist padrão.

screen folder update <id> [--name NAME] [--parent ID | --root] [--default-playlist-id ID | --clear-default] [--expect-rev REVISION] [--note TEXT]
screen folder update <id> --unprotect [--expect-rev REVISION] [--note TEXT]

Informe pelo menos um entre --name, --parent, --root, --default-playlist-id, --clear-default ou --unprotect.

screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --name "Northern"
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --root
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --default-playlist-id pl_01EXAMPLEPLAYLIST000000 --expect-rev 3
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --clear-default
screenrig screen folder update sfd_01EXAMPLEFOLDER000000000 --unprotect --note "Menu boards move next week"

Uma pasta não pode ser movida para dentro de si mesma nem de uma pasta dentro dela, e valores iguais aos atuais não alteram nada. Uma movimentação ou uma mudança de padrão reavalia as telas dentro dela em cerca de 15 segundos, e data.levels lista as campanhas em cujo público de pasta essas telas entraram ou saíram (source campaign) e as playlists padrão de pasta que elas ganharam ou perderam (source folder).

Uma renomeação tem efeito imediato em uma pasta protegida. Uma movimentação, ou uma playlist padrão, de uma pasta que é ou contém uma protegida responde pending_review com uma revisão protected_change que um segundo aprovador decide (um aprovador diferente de você e da pessoa para quem você trabalha; senão, second_approver_required, saída 3). Nada muda até lá, então não repita a escrita; --note diz ao aprovador o motivo. Uma pessoa que pode aprovar protege uma pasta no dashboard; o CLI apenas propõe remover a proteção com --unprotect. Veja Pastas protegidas. Um chamador limitado a pastas de telas altera apenas pastas dentro do seu escopo e as move apenas para uma pasta pai dentro dele (outside_screen_scope, saída 3), e nunca a proteção de uma pasta que o escopo nomeia.

Excluir uma pasta de telas; suas telas e pastas sobem um nível.

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

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

Exclui apenas a pasta: suas telas e pastas sobem para a pasta pai (a raiz do projeto, se não houver) e essas telas reavaliam sua playlist. data é id, deleted true e levels, as campanhas e playlists padrão de pasta que as telas movidas ganharam ou perderam, com reach_before e reach_after de uma campanha. Um público de campanha que nomeia a pasta recusa a exclusão com resource_conflict (saída 5): altere ou exclua essas campanhas primeiro.

Um chamador limitado a pastas de telas exclui apenas pastas dentro do seu escopo, nunca uma pasta que o escopo nomeia (outside_screen_scope, saída 3). Uma pasta que é ou contém uma pasta protegida responde pending_review com uma revisão protected_change que um segundo aprovador decide, então não repita a escrita; --note diz ao aprovador o motivo.