Programe telas a partir de uma planilha

Da planilha às telas

1. Comece pelo modelo. Salve o modelo como CSV ou XLSX, ou use sua própria planilha com as mesmas colunas.
2. Preencha uma linha por linha de programação. Indique a tela (ou uma pasta ou uma tag), o arquivo, o início e o fim.
3. Importe. Solte o arquivo na caixa de diálogo Importar da aba Programação do dashboard, ou execute screenrig schedule import FILE.
4. Corrija as linhas com erros. Cada erro indica a linha, a coluna e um código. Edite a célula na caixa de diálogo, ou edite a planilha e importe de novo.
5. Verifique a prévia. Ela lista os níveis que a planilha cria, os que altera ou remove e o calendário das telas que ela afeta.
6. Publique. Todas as linhas são aplicadas juntas ou nenhuma é.

As etapas 1 a 5 não gravam nada. Uma tela precisa de um fuso horário (screen set-timezone) e de uma playlist padrão (screen assign) antes que uma linha possa programá-la, e um arquivo precisa ser uma imagem ou um vídeo aprovado.

A planilha

A primeira linha dá nome às colunas. Cada linha seguinte é uma linha de programação. Linhas em branco são ignoradas. Uma planilha é um arquivo CSV (UTF-8, separado por vírgula ou ponto e vírgula) ou uma pasta de trabalho XLSX, e uma pasta de trabalho XLSX é lida a partir da primeira planilha.

Os cabeçalhos são comparados sem considerar maiúsculas, espaços e pontuação. Uma coluna que nada lê é ignorada, e a prévia a lista. Uma linha precisa de target, de content e de pelo menos um entre start, end, days ou uma janela diária.

Screen,File,Start,End,Timezone,Days,Daily start,Daily end,Priority,Name
LOBBY-01,welcome-spring.jpg,2026-11-05 18:00,2026-11-08 02:00,America/Los_Angeles,,,,0,
folder:Casino Floor,happy-hour.mp4,2026-11-05,2026-11-30,,Mon-Fri,16:00,19:00,5,Happy hour
tag:elevators,playlist:Holiday loop,2026-12-01 09:00,2026-12-26,,,,,0,

• A linha 2 reproduz welcome-spring.jpg na tela com o código LOBBY-01 das 18h de 5 de novembro até as 2h de 8 de novembro, horário do Pacífico.
• A linha 3 reproduz happy-hour.mp4 em todas as telas da pasta Casino Floor e das pastas dentro dela, das 16h às 19h nos dias úteis, de 5 de novembro ao fim de 30 de novembro.
• A linha 4 reproduz a playlist Holiday loop em todas as telas com a tag elevators, das 9h de 1º de dezembro ao fim de 25 de dezembro.

Alvos

Um alvo é um destes:

• Uma tela. O id de uma tela, o valor de qualquer campo da tela (um código de sala, um número de loja) ou o nome da tela. --code-field ou code_field limita a correspondência a um campo, como code ou room_id.
• Uma pasta. folder:NAME ou folder:Parent/Child. Alcança a pasta e todas as pastas dentro dela.
• Uma tag. tag:NAME alcança todas as telas com a tag.

Vários alvos em uma célula são separados por ; ou |, como em LOBBY-01;LOBBY-02|tag:elevators.

Conteúdo

• Um arquivo. O nome de um arquivo de mídia do projeto, ou o nome original de um upload convertido. O arquivo é reproduzido em tela cheia. O primeiro commit que usa um arquivo cria a playlist de um arquivo Scheduled: FILE, e as importações seguintes a reutilizam.
• Uma playlist. playlist:NAME ou o id de uma playlist. A playlist tem uma versão aprovada e não é um template.

Horários

• Datas e horários. 2026-11-05 18:00, 2026-11-05T18:00, 11/5/2026 6:00 PM e células de data de planilha são lidos. Um horário com deslocamento, como Z ou +02:00, é recusado.
• O relógio próprio de cada tela. Os horários são lidos no relógio das telas que a linha alcança, então 18:00 é 18h onde quer que a tela esteja.
• Outro fuso horário. Uma célula timezone (ou o timezone da requisição) indica que a linha está escrita nesse fuso. Os horários são convertidos para o fuso das telas quando todas as telas da linha compartilham o mesmo fuso. Uma linha que alcança telas em vários fusos deixa timezone vazio e lê o relógio próprio de cada tela.
• Uma data sozinha como fim encerra esse dia: 2026-11-30 termina ao fim de 30 de novembro. Uma data sozinha como início começa à meia-noite.
• Sem fim mantém a linha em reprodução até que uma importação posterior a remova. A prévia avisa com open_end.
• Dias. Mon-Fri, Mon,Wed,Fri, Sat,Sun, weekdays, weekends ou daily. Uma linha com days e sem janela diária reproduz o dia todo nesses dias.
• Uma janela diária. daily start e daily end informam as horas de cada dia, como 16:00 e 19:00 ou 4:00 PM e 7:00 PM. Informe os dois. Um fim igual ou anterior ao início atravessa a meia-noite e pertence ao dia em que começa. Sem days, a janela vale todos os dias.

Prévia e erros

A prévia verifica cada linha e cada célula antes que algo seja gravado. Uma linha com erro é exibida com suas células, e cada erro indica a coluna, um código e o que alterar.

Dois avisos não interrompem uma importação. open_end marca uma linha sem fim. outranked marca uma linha sobre a qual um nível compartilhado (uma linha para várias telas, uma pasta ou uma tag) é reproduzido em uma tela.

Uma planilha sem linhas, um arquivo que não é UTF-8, mais de 5.000 linhas, um arquivo acima de 8 MiB ou um commit que gravaria mais de 400 programações próprias de telas é recusado com o motivo.

Níveis

Linhas que coincidem em conteúdo, horários, prioridade, nome e display viram um nível. O alvo não entra na comparação, então dez linhas que reproduzem o mesmo arquivo nos mesmos horários em dez telas formam um nível.

• Uma tela cria uma entrada na programação própria dessa tela.
• Várias telas, uma pasta ou uma tag criam um nível compartilhado, uma campanha sobre esse público. Um nível compartilhado prevalece sobre os níveis próprios de uma tela.

Agrupar transforma as 200 telas de um local em uma campanha e não em 200 entradas, e uma correção na planilha altera um nível. A coluna name dá nome a um nível compartilhado. Sem ela, o nível recebe o nome da importação, do conteúdo e do alvo, como em Spring promos: happy-hour.mp4 on Casino Floor.

Importar de novo

O name de uma importação a identifica, e o padrão é import. Ao importar de novo com o mesmo nome:

• atualiza os níveis que criou, mesmo quando as datas de uma linha mudaram;
• adiciona os níveis das linhas novas;
• remove os níveis cujas linhas não estão mais na planilha;
• não altera nada quando a planilha é a mesma.

Os níveis criados por uma importação a carregam em seu id (as entradas de uma tela começam com imp_) e as campanhas levam uma marca import. Os níveis que você criou à mão nunca são tocados. Use um nome para cada planilha e um nome diferente para outra.

Executar uma importação

Dashboard

Abra a aba Programação de um projeto e escolha Importar. Solte um arquivo CSV ou XLSX. A caixa de diálogo mostra uma tabela com as linhas e cada erro ao lado de sua célula, e você edita a célula no local. Em seguida ela mostra o calendário composto das telas que a importação altera. Publicar confirma a importação.

Linha de comando

screenrig schedule template --output schedule.csv
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles --commit

schedule import gera a prévia e não grava nada. --commit aplica a planilha quando todas as linhas são válidas.

O comando sai com 0 para uma planilha válida, 8 quando há linhas com erros (nada é gravado) e 5 quando o projeto mudou desde a prévia (execute de novo). FILE é um arquivo .csv, .xlsx ou .json, ou - para a entrada padrão. Um arquivo JSON contém um array de objetos de linha, ou {"rows": [...]}, indexados pelo nome da coluna.

API

Envie a planilha como linhas JSON, ou como corpo CSV ou XLSX com as configurações como parâmetros de consulta. A prévia exige acesso de leitura. O commit exige uma credencial com acesso de escrita, concedida por uma pessoa que possa aprovar no dashboard.

curl -s https://api.screenrig.ai/api/schedule/imports/preview \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Spring promos",
    "timezone": "America/Los_Angeles",
    "rows": [
      {"target": "LOBBY-01", "content": "welcome-spring.jpg", "start": "2026-11-05 18:00", "end": "2026-11-08 02:00"},
      {"target": "folder:Casino Floor", "content": "happy-hour.mp4", "start": "2026-11-05", "end": "2026-11-30",
       "days": "Mon-Fri", "daily_start": "16:00", "daily_end": "19:00", "priority": 5, "name": "Happy hour"}
    ]
  }'

A mesma planilha como arquivo:

curl -s "https://api.screenrig.ai/api/schedule/imports/preview?name=Spring%20promos&timezone=America/Los_Angeles" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: text/csv" \
  --data-binary @schedule.csv

A resposta, resumida:

{
  "name": "Spring promos",
  "valid": false,
  "fingerprint": "FINGERPRINT",
  "columns": ["target", "content", "start", "end", "days", "daily_start", "daily_end", "priority", "name"],
  "summary": {"rows": 2, "rows_with_errors": 1, "levels": 1, "creates": 1, "updates": 0,
              "unchanged": 0, "removes": 0, "screens": 1, "playlists": 1},
  "rows": [
    {"row": 2, "status": "ok", "level": "LEVEL_KEY"},
    {"row": 3, "status": "error",
     "errors": [{"column": "content", "code": "unknown_file",
                 "message": "No file or playlist is named \"happy-hour.mp4\"."}]}
  ],
  "levels": [{"key": "LEVEL_KEY", "action": "create", "home": "screen", "screen_id": "scr_LOBBY",
              "content": {"kind": "file", "id": "med_WELCOME", "name": "welcome-spring.jpg"},
              "screens": 1, "priority": 0, "from": "2026-11-05T18:00", "until": "2026-11-08T02:00", "rows": [2]}],
  "removals": []
}

rows[].cells retorna as células de cada linha como a planilha as forneceu, para que o cliente as corrija e envie as linhas novamente. valid é true quando nenhuma linha tem erro. calendar tem o formato de GET /api/schedule/calendar e mostra as telas que a importação altera como ficariam após um commit.

O commit envia a mesma planilha e o fingerprint da sua prévia, como membro do corpo JSON ou como parâmetro de consulta com um arquivo. Envie um Idempotency-Key para repetir com segurança.

curl -s https://api.screenrig.ai/api/schedule/imports \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Idempotency-Key: spring-promos-1" \
  --header "Content-Type: application/json" \
  --data @commit.json

A resposta traz preview e applied, as contagens do que foi criado, atualizado, deixado sem alteração e removido, com as telas gravadas e as playlists criadas. Um commit é recusado, e não grava nada, como:

GET /api/schedule/imports/template?format=csv e format=xlsx respondem com o modelo.

Limites

• 5.000 linhas e 8 MiB por planilha.
• 32 níveis próprios por tela. Uma organização comporta até 100 campanhas em todos os seus projetos, e cada nível compartilhado é uma delas.
• 400 programações próprias de telas gravadas por commit. Uma linha de pasta ou de tag alcança qualquer número de telas.
• O nome de uma importação tem de 1 a 80 caracteres.

Relacionado

• CLI de sinalização: programações, takeover e campanhas para uma tela ou uma frota.
• Referência da API: as rotas /api/schedule/imports e seus problemas.
• Autenticação: acesso Somente leitura, Propor e Gerenciar.