Escolha o caminho de criação correto

Assista ser construído

Filme / Construir um app de quiosque com o SDK

3:07

Use screenrig após a configuração da sessão em Início.

Escolha o caminho do conteúdo

A geração compõe a arte e a tipografia juntas, então coloque todo o texto no prompt. Os cartões desenham o texto no Player, então uma palavra ou um número alterado não exige uma nova imagem estática. Arquivos finalizados fornecidos por você não precisam de geração. A animação, por si só, não exige nenhum dos dois.

Gerar uma imagem estática finalizada

O agente envia um prompt mais aspect_ratio e quality. O screenRIG retorna um objeto de mídia med_… na loja de mídia da conta. O chamador não reenvia os bytes. Busque os bytes originais apenas para inspeção; caso contrário, mantenha a referência med_… em uma playlist.

Seu próprio media upload permanece válido. Não gere quando você já tem o arquivo. Vídeo ao vivo, stream, iframe e páginas de app web são primitivas de playlist, não imagens estáticas geradas.

A qualidade é low, medium, ou high (padrão medium). A proporção é 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, ou 2:3 (padrão 16:9). --quality altera o nível de detalhe da imagem estática e, portanto, quantos tokens ela usa:

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality QUALITY] [--tag TAG]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

O envelope informa um id med_…. Nunca imprime bytes de imagem.

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

Adicionar uma trilha sonora

Uma playlist pode conter uma trilha sonora: uma lista ordenada de faixas MP3 que toca continuamente enquanto as páginas mudam. Transições de página nunca param, reiniciam ou fazem fade na música. A trilha sonora é uma configuração da playlist, não um sétimo primitivo, então não tem retângulo ou camada na tela.

Envie cada faixa com media upload. Arquivos MP3 são enviados como estão; arquivos WAV, AAC, M4A, OGG e FLAC são transcodificados para MP3 primeiro. Cada faixa vira um objeto de mídia audio com um id med_… e duração.

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

Nomeie as faixas na playlist audio membro; ela contém de 1 a 128 faixas. As faixas tocam em ordem, uma após a outra. loop (padrão true) reinicia na primeira faixa após a última; volume (padrão 1, de 0 a 1) escala o volume próprio do Player.

{
  "name": "Lobby",
  "audio": {
    "tracks": [
      { "id": "intro", "media_id": "med_01EXAMPLEINTRO000000000" },
      { "id": "bed", "media_id": "med_01EXAMPLEBED00000000000" }
    ],
    "loop": true,
    "volume": 0.8
  },
  "pages": [
    { "id": "welcome", "audio_cue": { "track": "intro", "restart": true } },
    { "id": "menu" }
  ]
}

Uma página pode conter um audio_cue opcional. Quando essa página aparece, o Player troca para a faixa nomeada desde o início; se essa faixa já estiver tocando, ela reinicia apenas quando restart for true. A sequência continua então da faixa indicada. Indicações são sugestões: um Player as aplica com um fade curto ou as pula quando a faixa não está pronta. Páginas sem indicação não alteram a música. Campos da página além de id e audio_cue são omitidos no exemplo acima.

Substituir uma playlist substitui também sua trilha sonora; deixe audio de fora para removê-la. Vídeos na tela permanecem sem som, então a trilha sonora é o único som que uma tela reproduz.

Vincular uma página a uma faixa

Para um álbum ou livro com uma página por faixa, ou qualquer página que dure exatamente o tempo de uma faixa, vincule a página à sua faixa.

Defina a página advance para { "mode": "audio_end" }. A página aplica seu audio_cue quando aparece, como qualquer comando, e termina quando essa faixa termina, do mesmo modo que uma página media_end termina com seu vídeo. A página deve conter um audio_cue e a playlist uma trilha sonora audio. Primitivas de imagem e vídeo seguem as regras duration: sem dwell_ms, e one_at_a_time: true em todo seletor dinâmico (all, tag, folder ou ids com mais de um id), mesmo quando corresponde a um objeto hoje. Uma primitiva stream ainda precisa de uma página duration, e um aplicativo na página nunca é seu controlador. max_ms é uma dica de segurança opcional; o servidor define o prazo a partir da duração da faixa, então deixe de fora. Se o Player não puder reproduzir a faixa, a página ainda dura o tempo da faixa.

Defina cued para true no membro audio para parar a trilha sonora após cada faixa. Uma faixa programada toca somente quando uma página audio_cue a inicia. Ela continua tocando sob quaisquer páginas comuns que seguem sua página até terminar, e então a trilha sonora fica silenciosa até o próximo comando, assim uma página e sua faixa permanecem vinculadas, com qualquer número de páginas comuns entre páginas vinculadas. loop não afeta uma trilha sonora programada, e cued padrão é false.

{
  "name": "Album",
  "audio": {
    "tracks": [
      { "id": "song1", "media_id": "med_01EXAMPLESONG1000000000" },
      { "id": "song2", "media_id": "med_01EXAMPLESONG2000000000" }
    ],
    "cued": true
  },
  "pages": [
    { "id": "song1-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song1", "restart": true } },
    { "id": "interlude", "advance": { "mode": "duration", "after_ms": 8000 } },
    { "id": "song2-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song2", "restart": true } }
  ]
}

Campos da página além de id, advance e audio_cue são omitidos do exemplo acima.

Colocar um cartão para texto ao vivo

Um cartão integrado desenha texto, um menu, uma tabela, um relógio ou um medidor no próprio Player, então o texto continua editável e um novo valor chega a todas as telas sem uma nova imagem estática. cards list mostra os tipos, card create cria uma instância, e a playlist a coloca como uma primitiva card. card data put grava seus valores ao vivo. Cartões lista todos os tipos e layouts.

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

Mostrar um dashboard atrás de um login

Uma conexão web faz login em um site como uma pessoa faria, com uma conta de serviço, e uma visualização web mostra uma página dele. Serve para dashboards do Salesforce, Looker Studio, Datadog, HubSpot e qualquer outro site que não tenha link público. Um navegador na borda do screenRIG abre a página já logado e o Player mostra uma imagem dela, redesenhada a cada refresh_s segundos (de 60 a 86.400, 300 por padrão). Todas as telas do mesmo tamanho compartilham uma imagem, então mais telas não geram mais logins, e a imagem só é desenhada enquanto a playlist de uma tela mostra a visualização. As conexões e visualizações do Grafana, do Power BI e do Tableau funcionam do mesmo jeito e estão na referência da API.

1. Crie uma conta de serviço no site que possa ler apenas os dashboards que suas telas mostram. Toda captura faz login como ela.
2. Crie a conexão com kind web e as configurações abaixo. A senha é secret.
3. Crie uma visualização de uma página: o endereço https dela como url e, como wait_for, um seletor CSS de um elemento que só aparece quando a página está logada e pronta, para que uma página de login expire em vez de ser desenhada. clip desenha apenas a parte da página que um seletor nomeia, e wait_ms (até 10.000) espera por gráficos tardios.
4. Coloque o embed_url da visualização em uma primitiva iframe com content_fit fill.

{
  "kind": "web",
  "name": "Sales dashboard",
  "config": {
    "login_mode": "auto",
    "login_url": "https://login.example.com/sign-in",
    "username": "screens@example.com"
  },
  "secret": "ACCOUNT_PASSWORD",
  "totp_secret": "AUTHENTICATOR_KEY"
}

{
  "connection_id": "bic_01EXAMPLECONNECTION0000",
  "name": "Sales this week",
  "url": "https://app.example.com/dashboards/sales",
  "refresh_s": 300,
  "wait_for": "#sales-total"
}

A senha, a chave TOTP e os cookies ficam ao lado de config, são armazenados selados e nunca mais são mostrados: uma leitura diz se cada um está definido. Um secret ou totp_secret vazio, ou cookies: [], o remove.

• Os cookies vêm primeiro. A conexão mantém um único conjunto de cookies selado: o que você colou e depois os cookies que cada captura devolve. Uma captura envia o conjunto de cookies e nenhuma credencial, e só faz login quando não há conjunto ou a última captura chegou a uma página de login. Um site que guarda a sessão fora dos cookies faz login em toda captura, então dê à visualização um refresh_s longo.
• A senha vai só para a página de login. Ela é digitada em login_url e nos passos goto, nunca no endereço de uma visualização. Adicionar um endereço a qualquer um dos dois exige a senha na mesma solicitação, então um membro que não pode ler a senha não pode apontá-la para uma página própria.
• A conta é protegida. Um login recusado (bi_web_login_failed ou bi_web_otp_required) espera 5 minutos, depois 15, 60 e 120, e o quinto seguido interrompe a conexão até você mudar as credenciais ou as configurações de login, então no máximo 3 tentativas acontecem na primeira hora. Um login que termina de outro jeito (tempo esgotado, bloqueio, página que não abriu) espera 15 minutos. Use uma conta de serviço somente leitura.
• Alguns sites não podem ser automatizados. Um site que aprova logins no celular, verifica dispositivos ou mostra um CAPTCHA precisa de um conjunto de cookies (login_mode none) ou de uma conta de serviço que o site isente.

O Player mantém a última boa imagem enquanto uma captura falha, e o status da visualização traz um destes códigos:

screenrig bi connection test ID faz login e informa o resultado. O session de uma conexão diz em que pé estão os cookies e o login dela: idle, active, login_needed, paused, stopped ou expired.

Filtrar tags e lotes de reprodução

A mídia suporta até 32 tags únicas, cada uma com 1 a 32 letras ou dígitos. Substitua o conjunto inteiro por screenrig media update med_ID --tags Summer,Drinks. --tag Summer substitui por uma tag; --clear-tag limpa todas as tags. media list --tag Summer corresponde à associação em qualquer lugar do conjunto. Tags são sensíveis a maiúsculas e minúsculas e nunca são autorização.

Um seletor dinâmico pode usar um tag ou um objeto filtro tags:

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

all requer todas as tags listadas, any requer pelo menos uma, e none exclui qualquer tag listada. Grupos presentes combinam com E; grupos omitidos não impõem condição. Forneça pelo menos um grupo não vazio. Cada grupo aceita até 32 tags únicas. tag e tags são mutuamente exclusivos. Um filtro só com none seleciona toda mídia pronta daquele tipo primitivo, exceto as tags excluídas. Seletores de imagem selecionam imagens e seletores de vídeo selecionam vídeos.

O pool de candidatos contém até 1.024 mídias prontas por seletor, com 1.024 referências de mídia no instantâneo completo do loop. Uma correspondência maior retorna um erro; afine os filtros. batch_size é um limite separado de 1–1.024 itens por visita à página. Em uma página media_end, one_at_a_time: false reproduz o próximo lote em sequência; omitir batch_size reproduz o restante da passagem. one_at_a_time: true reproduz um item por aparição e permite apenas um tamanho de lote omitido ou batch_size: 1. Duração, aplicação e páginas audio_end requerem one_at_a_time: true. Imagens em media_end também requerem dwell_ms; vídeos não podem fazer loop nessa página.

O Player resolve cada primitivo de mídia dinâmico em uma requisição na inicialização da playlist e em cada limite de loop. A associação é congelada durante o loop. Uploads, remoções, alterações de marcação e limites de disponibilidade não regeneram o manifesto. Na próxima atualização, itens removidos ou recém-excluídos saem da fila pendente; novas correspondências entram quando a passagem atual termina. Um lote final pode conter menos que o número solicitado; ele não reabastece da próxima passagem. A ordem do nome do arquivo ordena por nome, depois ID da mídia. A ordem aleatória embaralha uma vez por passagem completa, preservando a ordem restante entre atualizações do loop. A ordem ponderada segue seus pesos, abaixo. O cursor é local para a tela, playlist, página e primitivo, persiste após reinício e reinicia quando o filtro, ordem ou política de lote muda. A reprodução offline usa o último snapshot bem-sucedido. Correspondências vazias pulam o primitivo e qualquer página vazia resultante.

Salve o objeto seletor acima como selector.json, então inspecione seu catálogo de candidatos atual antes de publicar:

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

A pré-visualização retorna matched_count, ordenada por nome de arquivo candidates com IDs de mídia e tags, e a política selector normalizada. Com ordem aleatória, mostra o pool e a política de embaralhamento; não escolhe o embaralhamento do Player, não avança um cursor, não cria uma concessão de reprodução nem altera um manifesto. Com ordem ponderada, retorna weight e share_percent de cada candidato, além de cycle. --rect WxH (API rect: {width, height}) é o tamanho do slot e é obrigatório com fit: "aspect"; as correspondências deixadas de fora aparecem em excluded com o motivo aspect_mismatch. Seletores de imagem passam --primitive image. A API é POST /api/selectors/preview com { "primitive": "video", "selector": ... }. Usa o projeto autenticado e as mesmas regras de correspondência da reprodução. Alterações no catálogo após a pré-visualização são resolvidas no próximo ciclo da reprodução.

A exportação de pacote estático congela correspondências dinâmicas como IDs exatas. Preserva reprodução uma a uma ou completa; uma sequência de tempo limitada usando batch_size com one_at_a_time: false requer remover esse campo ou escolher IDs explícitos antes da exportação. Isso evita perda silenciosa do cursor de lote em tempo de execução em um pacote estático.

Rotação ponderada e ajuste de proporção

order: "weighted" alterna os criativos de um slot por peso, de modo que cada patrocinador mantém sua participação nas reproduções. weights mapeia um ID de mídia (med_...) ou tag:NAME para um inteiro de 1 a 1.000, com no máximo 64 chaves. Funciona com by de all, tag ou folder:

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

Pesos de 50, 30 e 20 entregam exatamente 5, 3 e 2 de cada 10 reproduções, em todo ciclo, e uma reinicialização retoma no meio do ciclo. O peso de um item é a chave do seu ID de mídia, quando presente; caso contrário, a primeira chave tag:NAME, em ordem alfabética, entre as tags que ele carrega, dividida igualmente entre os itens da seleção que a compartilham, de modo que a participação de um patrocinador se mantém qualquer que seja o número de criativos; caso contrário, o item conta como seu próprio grupo com peso 1. Um ciclo tem no máximo 4.096 reproduções; as participações são arredondadas para ele somente quando a proporção exata exige um ciclo mais longo.

A ordem ponderada reproduz um item por visita, então defina one_at_a_time: true ou batch_size: 1. weights é obrigatório com a ordem ponderada e permitido somente com ela; caso contrário, a gravação retorna invalid_request. Os Players web, Android, Apple, Windows e Linux implementam a ordem ponderada a partir das versões que declaram a capacidade de host selector.weighted. Um Player mais antigo reproduz o seletor de forma aleatória, e os diagnósticos do manifesto trazem selector_order_downgraded.

fit: "aspect" em um seletor dinâmico mantém apenas arquivos cuja largura sobre altura está dentro de 5% da do retângulo do slot, incluindo um video wall ou moldura de display, lida quando o seletor é resolvido. Um slot em retrato nunca reproduz um arquivo em paisagem. Nenhuma mudança no Player é necessária.

screenrig media selector-preview imprime a participação esperada de cada seletor ponderado ou ajustado por proporção, e o editor de páginas do painel mostra a mesma tabela no inspetor. A exportação de pacote estático congela um seletor ponderado como IDs exatas na ordem do nome do arquivo; os pesos não são mantidos.

Tokens de tela em seletores de tag

O tag de um seletor de tag, e cada entrada do seu filtro tags, pode ser {screen.field.NAME} ou {screen.id}, o identificador da tela sem o prefixo scr_, que é uma tag. O servidor preenche o token para cada tela ao montar o manifesto e o snapshot de seletores dessa tela, de modo que uma playlist reproduz a mídia própria de cada tela. Marque a mídia com Lobby ou Garage, defina o campo de cada tela com screenrig screen update scr_ID --field zone=Lobby e dê ao slot este seletor:

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

O valor preenchido segue as regras de tag: de 1 a 32 letras ou dígitos. Uma tela sem o campo, ou cujo valor não é uma tag, não seleciona nada: não reproduz nenhum arquivo desse slot, e os diagnósticos do manifesto trazem screen_fact_missing ou screen_fact_invalid. Alterar um campo gera de novo o manifesto dessa tela. Um seletor com token não pode ser visualizado (media selector-preview exige uma tag concreta) nem congelado por playlist export.

Tokens de tela em endereços de iframe e params de aplicativo

Em um iframe, src e fallback_src podem trazer tokens de tela no caminho, na query ou no fragmento de um endereço http ou https, e o mesmo vale para params, opcional, de uma primitiva application: até 16 nomes de 1 a 32 letras minúsculas, dígitos ou sublinhados (ticket e policy são reservados) com valores de até 512 caracteres. O servidor os preenche para cada tela:

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

A escrita armazena o modelo como escrito, chaves incluídas. O manifesto de cada tela traz seu próprio endereço, com cada valor codificado em percentual para seu lugar na URL: um kiosk_id de B 2&3 vira B%202%263. Um token no esquema, nas credenciais, no host ou na porta, ou em um link do YouTube, um link de documento do Google ou Microsoft ou um endereço de visualização de BI, é invalid_request em src (ou fallback_src). A publicação pula a verificação de enquadramento para um src com modelo, e as prévias mostram o modelo como escrito.

Uma tela que não tem um valor (um campo não definido, sem localização), ou cujos valores preenchem um endereço com mais de 2048 caracteres ou com um segmento de caminho . ou .., não recebe esse iframe ou aplicativo, e os diagnósticos de seu manifesto trazem screen_fact_missing ou screen_fact_invalid; uma página que fica vazia é descartada. Toda escrita que alcança essa tela (uma escrita de playlist, screen assign, screen update, uma atribuição em frota, uma revisão aprovada) responde com um aviso screen_fact_missing que nomeia os tokens, os primeiros 20 ids de tela e quantas são. Alterar um campo ou a localização renova o manifesto das telas afetadas.

Para um aplicativo, cada param preenchido é anexado ao endereço de lançamento depois de ticket, codificado em percentual, no máximo 4096 caracteres juntos, de modo que o aplicativo o lê em location.search (SDK). Os params de lançamento chegam ao app web do Player e aos Players que o executam (Samsung Tizen, BrightSign, LG webOS e Vega); os Players Qt, Android, Apple e Windows carregam o aplicativo do seu pacote local e não enviam nenhum. O campo url de um modelo pode ser um src de iframe inteiro, e seu valor pode ele mesmo trazer tokens de tela, preenchidos quando o manifesto é montado. Um seletor de tag usa {screen.id} e {screen.field.NAME} da mesma forma (acima). Os cartões mantêm seus próprios tokens {screen.…}.

Disponibilidade de mídia

screenrig media availability med_ID --file rule.json define quando os seletores dinâmicos (all, tag e folder) podem escolher um arquivo. --clear remove a regra e --expect-rev N protege a revisão da mídia. A API é PATCH /api/media/{id}/availability com If-Match e { "availability": {...} | null }. Definir uma regra exige acesso Manage; uma credencial Propose recebe insufficient_access.

A regra é a gramática de horário da programação, lida no fuso horário de cada tela, e tem pelo menos um membro: from e until (civil YYYY-MM-DDTHH:MM, until exclusivo), windows (semanal {days, start, end}), monthly ({day} ou {nth, weekday}, cada um com start e end opcionais), dates ({date, start, end}) e except (datas que removem uma ocorrência, incluindo as caudas após a meia-noite). Não tem data nem interaction. O criativo de um patrocinador para o fim de semana prolongado, disponível apenas nas noites de dias úteis dentro do período:

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

Somente os seletores leem a regra: um seletor explícito com id ou ids a ignora, assim como as referências de mídia dos cards, o áudio da trilha sonora e os criativos de anúncios. Um arquivo sai da seleção e volta no próximo loop da playlist de cada tela, em cerca de um minuto após o limite. Nenhuma revisão de playlist ou manifesto muda, e um Player offline mantém a última seleção até se reconectar. screenrig media selector-preview --timezone ZONE (UTC por padrão) lista em excluded os arquivos fora da regra naquele momento, com o motivo outside_window.

Voltar para a referência CLI do screenRIG.