screenRIG
EntrarComece

Cartões integrados

Adicione componentes ao vivo a uma playlist: menus, relógios, filas, pontuações, clima e medidores. Escolha um cartão, defina suas propriedades e publique.

Um cartão é um componente embutido em uma tela de playlist. Ele preenche seu retângulo com um relógio, menu, fila ou outro detalhe ao vivo, e pode ficar sobre imagens ou vídeo.

Layouts e âncoras

Defina layout e anchor no item da playlist, ao lado de card. layout é obrigatório.

layoutCaixa em unidades de design 1080panchor
fullToda a tela, paisagem ou retratonenhum
freeSeu próprio rect e layernenhum
center900 × 420, centralizadonenhum
wideA margem da tela é 80 do topo e da base e 30 dos ladosnenhum
headerToda a borda superior por 80nenhum
footerToda a borda inferior por 80nenhum
corner270 × 270, encostado no cantotop-left, top-right, bottom-left, bottom-right
chip240 × 70, afastado 30 das duas bordas mais próximastop-left, top-right, bottom-left, bottom-right
stripToda a borda por 120top, bottom, left, right

Os tamanhos escalam por min(canvas width, canvas height) / 1080. Um canvas 4K (3840 × 2160) mostra o mesmo tamanho aparente que 1080p, e um canvas retrato o mesmo que um paisagem. O design de um cartão segue a forma de sua caixa: faixa, paisagem, quadrado, retrato ou torre.

anchor é obrigatório para corner, chip e strip, e não permitido para full, free, center, wide, header e footer. Omitir rect e layer para todos os layouts exceto free: screenRIG os deriva da tela da página quando a playlist é salva. Um item free precisa do seu próprio rect e layer.

Compose uma página com um cartão full, center ou wide, mais cartões corner, chip e strip conforme necessário. Uma página contém no máximo um cartão full, center ou wide, no máximo um cartão corner ou chip por canto, e no máximo um strip por borda, mais um cartão com presença que compartilha essa borda. Um header e um footer são barras de largura total, 80 de altura, nas bordas superior e inferior, e uma página contém uma barra por borda: um header ocupa o slot strip da borda superior e um footer o da borda inferior, de modo que essa borda não contém um strip normal, enquanto um cartão com presença ainda pode compartilhá-la. Uma página pode conter tanto um header quanto um footer. Imagens, vídeos e itens web não são limitados por essas regras, e qualquer número de cartões free pode compartilhar uma página. Um corner ou chip em uma borda que contém um strip move-se para dentro além dele em 120, e além de um header ou footer em 80 (o maior quando uma borda contém ambos), para que nunca se sobreponham. Um cartão center, wide, header ou footer ignora faixas.

Um strip à esquerda ou à direita é a faixa nessa borda, 120 de largura e tão alta quanto o canvas. O cartão é desenhado como uma faixa horizontal e o Player o gira 90 graus em torno do centro da faixa: a faixa esquerda no sentido anti-horário, para que o texto leia de baixo para cima, e a faixa direita no sentido horário, para que o texto leia de cima para baixo.

O nível de um cartão decide seus layouts. Um cartão core usa todos os nove, restrito aos layouts que desenha: apenas os cartões header e footer usam esses dois. Um cartão fullscreen é feito para uma tela paisagem ou retrato cheia e usa apenas full. Um stinger é um bumper de transição de página e não usa layout. GET /api/card-types e screenrig cards show ID listam o nível e layouts de cada cartão.

Presença

Alguns cartões estão presentes apenas enquanto sua condição se mantém, como uma barra de alertas na borda inferior ou um chip “raio próximo”. Enquanto ausente, um cartão não desenha nada. Uma faixa de presença na mesma borda que uma faixa normal a substitui enquanto presente, e a faixa normal retorna depois. Um cartão com presença aparece e desaparece com movimento que combina com seu layout: faixas deslizam de sua borda, cantos e chips sobem e desaparecem, e cartões center, wide, header, footer, full e free desaparecem.

Erros de layout

Salvar uma playlist é recusado com card_layout_invalid (400) para layout ausente ou desconhecido, âncora ausente, desconhecida ou indesejada, um layout que o nível ou visualizações do cartão não aceitam, ou um rect ou layer que não é o derivado. É recusado com card_layout_conflict (400) quando dois cartões reivindicam o mesmo lugar em uma página. errors[0].field nomeia o membro.

Temas

Defina params.theme para neomustard (NeoMustard), cyanotype (Cyanotype), propaganda (Propaganda), signal (Signal), avant-garde (Avant Garde), bloom (Bloom), clear-dark (Clear Dark), clear-light (Clear Light) ou primetime (Primetime). Os cards em screenrig.ai abrem em Bloom e o controle de tema os alterna. Primetime é o tema animado, background none fornece um fundo transparente, e os layouts de canto e chip usam a placa compacta do tema.

Cartões Core, tela cheia e stinger

Cada cartão pode ser principal, em tela cheia ou stinger. Cartões principais se adaptam a qualquer layout e são os exibidos na página de Apps. Cartões em tela cheia ocupam toda a tela (paisagem ou retrato) e têm suas próprias páginas listadas na referência de cartões abaixo. O stinger é exibido entre duas páginas como transição.

Propriedades comuns

Essas propriedades controlam o tema e a posição de cada cartão. Defina-as em params.

NomeTipoPadrãoValores e limitesDescrição
themestring"neomustard""neomustard", "cyanotype", "propaganda", "signal", "avant-garde", "bloom", "clear-dark", "clear-light", "primetime"
backgroundstring"theme""theme", "none"nenhum pinta nenhum fundo, para sobreposição sobre vídeo.
accentstring, nulonullpadrão: "^#[0-9A-Fa-f]{6}$"Substitui o destaque do tema.
layoutstring"full", "free", "center", "wide", "corner", "chip", "strip"Onde o cartão é colocado (CONTRACT.md "Layouts"): full é a tela inteira, free qualquer retângulo que o host fornecer, center 900x420, wide é a tela com margem de 80 do topo e fundo e 30 dos lados, corner 270x270 encostado em um canto, chip 240x70 com margem 30 de um canto, strip 120 de altura ao longo de uma borda (tamanhos em pixels de design 1080p). Sem isso, um cartão ocupa full quando seu retângulo preenche a tela, caso contrário free.
anchorstring"top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"Em qual canto (canto e chip) ou borda (faixa) um layout fica. Canto padrão é superior direito e faixa inferior; os outros layouts não têm.

Propriedades estáticas e dinâmicas

Um cartão é uma instância no seu projeto: um id crd_ que guarda as propriedades estáticas do cartão e seu documento de dados ao vivo. Crie-o uma vez, coloque seu id em um item de página e altere seus valores quando quiser.

As propriedades estáticas são os params da instância: tema, localização, títulos e similares. Altere-as com card params e depois envie a playlist novamente para que ela as assuma. As propriedades dinâmicas são os valores marcados dynamic: true no contrato do cartão, como seções de menu, entradas de fila ou leituras de medidor. Elas ficam no documento de dados do cartão, que card data put substitui sem republicar a playlist.

Os Players aplicam padrões, depois parâmetros estáticos, depois as propriedades dinâmicas do documento. O documento ao vivo não pode alterar o estilo, e params nunca contém propriedades dinâmicas. Um cartão cujas propriedades dinâmicas obrigatórias ainda não têm documento permanece oculto até que um seja escrito.

Um cartão, um documento

Cada cartão tem seu próprio documento de dados, e cada item de página que contém seu id crd_ mostra esse documento. Dois cartões de Workplace Posts que mostram posts diferentes são dois cartões com ids próprios: uma gravação em um atualiza apenas os itens que contêm o id dele. Coloque o mesmo id em vários itens, em uma página ou em várias, quando devem mostrar o mesmo documento.

Feeds

Feeds são dados de terceiros buscados e armazenados em cache pelo backend e passados para o cartão pelo Player. Para clima, defina location com um nome, latitude e longitude. O backend deriva a chave do feed dessas propriedades estáticas; não envie um campo feed no item do canvas. Documentos de feed carregam atribuição de fonte e timestamps de busca. Cada referência de cartão nomeia seu esquema de feed e atribuição de fonte.

Mostre a atribuição de um feed onde quer que os dados dele apareçam: os cartões fazem isso por você. Um agente lê o documento que um cartão lê com GET /api/feeds/FAMILY, em que a família é o primeiro nome depois de Família e cartão em cada seção abaixo. Uma primeira leitura de um lugar novo responde 202 com Retry-After: 60 enquanto o screenRIG o busca, e todos os cartões de um mesmo lugar compartilham um documento.

Marés

Previsões de maré para uma estação, da NOAA CO-OPS: dados de domínio público dos Estados Unidos e de seus territórios.

  • Família e cartão: tides e tides
  • Definir: station, o ID de estação da NOAA de sete caracteres, ou location, que escolhe a estação de previsão mais próxima em um raio de 100 km. Um lugar sem estação tão próxima não gera nenhuma chave de feed: o cartão espera e a API responde 400 invalid_request.
  • Dados: preamares e baixa-mares de dois dias antes a três dias depois, mais uma série de 15 minutos para as estações que a NOAA prevê por harmônicos. As alturas estão em metros acima do MLLW e os horários em UTC. Atualizado a cada 6 horas.
  • Crédito: Tide predictions from NOAA CO-OPS, reformatted by screenRIG; not an official NOAA product.

Lançamentos de foguetes

Os próximos lançamentos de foguetes no mundo todo, do Launch Library 2 da The Space Devs.

  • Família e cartão: launches e launch-tracker
  • Definir: nada. Todos os cartões mostram a mesma lista.
  • Dados: os 20 próximos lançamentos com fornecedor, veículo, plataforma e órbita, atualizados a cada 15 minutos. Um lançamento continua na lista por 24 horas depois da decolagem, que é como um cartão mostra o resultado, e o lançamento na plataforma também recebe a cronologia da missão com até 20 eventos.
  • Crédito: Data: The Space Devs / Launch Library 2.

Recalls de medicamentos e alimentos

Recalls de um órgão de saúde ou de alimentos de um país.

  • Família e cartão: drugalerts e drug-alerts
  • Definir: country (us, ca ou gb) e category (drug, o padrão, ou food).
  • Dados: os últimos 90 dias, a classe I primeiro e, dentro de uma classe, do mais recente para o mais antigo, até 100. Estados Unidos: os relatórios de fiscalização da FDA via openFDA, datados pela data do relatório, sem os recalls concluídos e encerrados. Canadá: os recalls e alertas de segurança da Health Canada e da CFIA. Reino Unido: os recalls de medicamentos da MHRA (classes 1 a 3) e os alertas alimentares da Food Standards Agency. Atualizado a cada 3 a 6 horas.
  • Crédito: o de cada órgão, sob a sua licença aberta: openFDA (CC0), a Open Government Licence – Canada e a Open Government Licence v3.0.

Doenças respiratórias

Atividade semanal de gripe, COVID-19 e VSR.

  • Família e cartão: respiratory e respiratory-activity
  • Definir: country (us ou gb) e region: um estado, território ou DC dos EUA por nome ou código postal, ou a Inglaterra ou uma região da UKHSA. Uma região vazia é o país.
  • Dados: para cada vírus, um nível de muito baixo a muito alto, uma tendência (subindo, estável ou caindo, que o screenRIG calcula a partir das duas últimas semanas em relação às duas anteriores), o último valor e 26 semanas de histórico. Estados Unidos: os níveis e taxas semanais de internação hospitalar do CDC, atualizados a cada 6 horas. Inglaterra: a parcela de testes laboratoriais positivos da UKHSA, atualizada a cada 12 horas. A UKHSA não publica nível, então o screenRIG o define comparando a última semana com a mais alta das 52 últimas: abaixo de 5% é muito baixo, abaixo de 20% baixo, abaixo de 40% moderado, abaixo de 70% alto, e acima disso muito alto.
  • Crédito: o CDC, sem endosso do screenRIG pelo CDC, pelo HHS nem pelo governo dos EUA e com o conteúdo inalterado; a UKHSA, sob a Open Government Licence v3.0.

Almanaque

O que o cartão today acrescenta à data: datas comemorativas, os acontecimentos do dia na história, e o sol e a lua.

  • Família e cartão: almanac e today
  • Definir: language (ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk ou zh; en por padrão), country (um código ISO 3166-1), location ({screen.location} o preenche) e date. Um cartão sem nenhum deles mostra a história em inglês e os dias internacionais.
  • Dados: os feriados nacionais do país, suas datas comemorativas e os dias internacionais (os nomes dos feriados ficam em inglês seja qual for o idioma), até dez acontecimentos do dia do On This Day da Wikipédia e, com um local, nascer e pôr do sol, meio-dia solar, alvorecer e crepúsculo civis, duração do dia e fase da lua. Sol e lua são calculados, não buscados. O documento vai do dia anterior até dois dias à frente, então uma página vira à meia-noite local.
  • Crédito: os colaboradores da Wikipédia, sob a CC BY-SA 4.0.

Segurança ao ar livre

A leitura de calor que o cartão outdoor-safety mostra.

  • Família e cartão: outdoorsafety e outdoor-safety
  • Definir: location.
  • Dados: uma temperatura de globo de bulbo úmido estimada para terreno aberto sob sol pleno, calculada a partir do tempo no local: temperatura, umidade, vento, nuvens e altura do sol. Na sombra a leitura é menor. É uma estimativa, nunca uma leitura de sensor, e o documento diz isso. As observações são horárias, então defina staleMinutes do cartão como 120 ou mais.
  • Raios: o feed leva apenas calor. Defina show do cartão como heat, ou grave os raios nos dados do cartão.

Partidas do transporte

As próximas partidas de uma a quatro paradas de um provedor de transporte, na ordem de saída.

  • Família e cartão: departures e departures
  • Definir: provider (tfl, entur ou digitransit) e stops, os IDs de parada do provedor (separados por vírgulas na API). Encontre um ID com a busca de paradas do próprio provedor.
  • Dados: atualizados a cada minuto enquanto uma tela mostra o quadro. Uma partida cancelada continua na lista como cancelada, e uma parada sem partidas é um quadro vazio. Uma parada que o provedor não conhece faz falhar o quadro inteiro, e o último quadro permanece. A TfL só dá previsões ao vivo, então suas linhas não têm atraso.
ProvedorExemplos de ID de paradaCrédito
tfl940GZZLUOXC (Oxford Circus), 490008660N (uma parada de ônibus)Powered by TfL Open Data
enturNSR:StopPlace:337, NSR:Quay:568Contains data under the Norwegian licence for Open Government data (NLOD) distributed by Entur
digitransitHSL:1040129© Digitransit, CC BY 4.0

Bicicletas compartilhadas

As estações de bicicletas compartilhadas mais próximas de um local, de sistemas que publicam GBFS.

  • Família e cartão: bikeshare e bike-share
  • Definir: location ({screen.location} funciona) e, opcionalmente, system, um ID de sistema da MobilityData como Mobibikes_CA_Vancouver, dublin ou nextbike_bn. Sem system, quem atende é o sistema listado mais próximo cuja área contém o local, e um local que nenhum sistema listado cobre não gera chave: o cartão espera e a API responde invalid_request em system.
  • Dados: primeiro as estações mais próximas, até 40 em 20 km, cada uma com bicicletas, bicicletas elétricas, docas e status, atualizadas a cada minuto.
  • Sistemas: 28 cujo próprio feed traz uma licença que permite redistribuição e exibição comercial: Mobi (Vancouver) e City Bikes Helsinki sob ODbL, docomo (Tóquio) sob CC BY 4.0, os sistemas da JCDecaux (Dublin, Lyon, Toulouse, Nantes, Bruxelas, Luxemburgo, Valência, Liubliana) sob a Licence Ouverte, e a nextbike em Berlim, Colônia, Düsseldorf, Hannover, Nuremberg, Bonn, Viena, Linz, Innsbruck, Praga, Brno, Varsóvia, Wrocław, Zagreb, Barcelona, Gotemburgo e Estrasburgo sob CC0.
  • Crédito: o operador, sob a sua licença.

Publicar um canvas de cartão

Siga Início para instalar o plugin oficial, selecionar seu projeto e associar um Player. Crie o cartão, coloque seu id em uma playlist e publique-a. Esta página usa o cartão de medidor no layout center.

Salve as propriedades estáticas do cartão como gauge-params.json:

{"theme":"neomustard"}

Crie o cartão com a CLI incluída no plugin. O resultado traz o id crd_ dele.

screenrig card create --type gauge --file gauge-params.json

Ou chame a API com o tipo e seus parâmetros. A resposta 201 traz o id do cartão.

curl --request POST "https://api.screenrig.ai/api/cards" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"type":"gauge","params":{"theme":"neomustard"}}'

Salve o seguinte como playlist.json, com o id do seu cartão no lugar de crd_01EXAMPLEGAUGE000000000. O item de página envia apenas o id e seu layout: os params e os dados do cartão ficam com o cartão.

{
  "name": "Live gauge",
  "pages": [
    {
      "id": "main",
      "canvas": {
        "width": 1920,
        "height": 1080,
        "background": "#000000FF",
        "viewport_fit": "contain"
      },
      "transition": {
        "type": "crossfade",
        "duration_ms": 500
      },
      "advance": {
        "mode": "duration",
        "after_ms": 15000
      },
      "primitives": [
        {
          "id": "gauge",
          "primitive": "card",
          "card": "crd_01EXAMPLEGAUGE000000000",
          "layout": "center",
          "content_fit": "fill"
        }
      ]
    }
  ]
}

Use autenticação API para sua autorização. Um token de agente já nomeia seu projeto, então os exemplos não enviam o cabeçalho ScreenRig-Project; se enviar, deve corresponder ao projeto do token. Mantenha os valores do token fora dos arquivos de playlist.

curl --request POST "https://api.screenrig.ai/api/playlists" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data @playlist.json

A resposta identifica a playlist com um id pl_. Uma resposta pending_review aguarda a revisão do projeto antes de entrar no ar. Para alterar propriedades estáticas, atualize o cartão com screenrig card params crd_ID --file gauge-params.json (PATCH /api/cards/{id} com {"params": {...}}) e depois envie novamente o documento {name, pages} com PUT /api/playlists/{id}: a playlist assume os parâmetros atuais do cartão quando é salva. O major de um cartão, opcional ao criá-lo, fixa seu contrato; omiti-lo seleciona a versão principal atual.

Itens de página antigos que nomeiam um tipo do catálogo com params e data embutidos, e as rotas /api/card-data/{key} por trás deles, continuam sendo aceitos. Cada resposta traz um aviso de descontinuação que nomeia o substituto: ids de instância de cartão de /api/cards, e /api/cards/{id}/data.

Escreva valores ao vivo

Prefira o CLI, que tem o comando. Salve o documento como gauge-data.json. O arquivo contém o documento em si, sem invólucro:

{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}
screenrig card data put crd_01EXAMPLEGAUGE000000000 --file gauge-data.json

As gravações substituem o documento inteiro e são conferidas com as propriedades dinâmicas do cartão: um documento que o cartão rejeita é recusado com card_data_invalid (409) e nada muda. Adicione --ttl 30m ou --expires-at INSTANT para esvaziar os dados em todas as telas, inclusive as offline, quando nada os atualiza. Uma notificação na condição card_data_stale avisa o projeto quando os dados de um cartão expiraram porque nada os renovou.

Ou chame a API diretamente. A API envolve o mesmo documento em um campo document. Documentos são objetos JSON de no máximo 1 MiB.

curl --request PUT "https://api.screenrig.ai/api/cards/crd_01EXAMPLEGAUGE000000000/data" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"document":{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}}'

Telas exibindo o cartão buscam novamente o documento e o atualizam no local. Leia um documento com GET /api/cards/{id}/data; sua revisão ETag pode ser enviada como If-Match na próxima gravação. Adicione Idempotency-Key para uma gravação repetível com segurança, e ttl_seconds ou expires_at ao lado de document para uma expiração. Liste os cartões do projeto com GET /api/cards; exclua um com DELETE /api/cards/{id} quando nenhuma playlist o usar.

Imagens nas propriedades do cartão usam media:<mediaId>, referenciando uma imagem pronta no mesmo projeto. Uma escrita de dados ao vivo requer que essas imagens estejam aprovadas. Nunca coloque uma URL de imagem em uma propriedade do cartão.

Atribuir e verificar com o CLI

Use o CLI embutido do plugin oficial com o mesmo projeto. Pegue o id da playlist da resposta da API e o id da tela de screen list, depois atribua e inspecione o resultado:

screenrig screen list
screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE
screenrig screen screenshot scr_EXAMPLE

A atribuição registra a playlist desejada. Inspecione evidências do Player antes de relatar que está tocando. Referência CLI · Referência API.

Referência do cartão

A referência do cartão cobre três grupos: cartões principais, cartões em tela cheia e o stinger. Cartões principais cabem em qualquer layout, cartões em tela cheia ocupam toda a tela, e o stinger toca entre páginas.

Cartões principais

Cartões em tela cheia

Stinger