Mídia
Um objeto de mídia é uma imagem estática, um clipe ou uma faixa de áudio MP3, armazenado como exatamente uma versão. Não há alternativa por dispositivo, então cada tela precisa decodificar o que media upload armazena.
Pastas de mídia organizam a biblioteca. Um ID de pasta começa com mfd_ e um ID de arquivo com med_. Um upload cai na raiz da biblioteca a menos que --folder nomeie uma pasta, media move e media folder update reorganizem a árvore, e um seletor de playlist by:folder reproduza os arquivos diretamente dentro de uma pasta, não os de suas subpastas. Uma organização contém no máximo 1000 pastas em todos os seus projetos, aninhadas em até 10 níveis, com nomes de 1 a 100 caracteres.
Uma mídia mantém seu ID quando o arquivo muda: media replace troca o arquivo no lugar, de modo que cada playlist e agenda que a usa reproduz o novo, e media versions lista todos os arquivos que o item já teve.
media upload#
Converter um arquivo local em bytes de entrega, enviá-lo e aguardar até que o objeto esteja pronto.
media upload <file> [--content-type TYPE] [--tag TAG] [--folder ID] [--no-wait] [--poll-ms MS]
[--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<file> | caminho | sim | nenhum | O quadro estático, clipe ou faixa de áudio de origem. O nome do arquivo torna-se o identificador humano em listagens, playlists e relatórios de reprodução, então nomeie-o pelo que mostra. |
--content-type TYPE | string | não | o tipo da extensão do arquivo | Declare o tipo de mídia da fonte para um arquivo cuja extensão não o indica. Um tipo que contradiz os bytes do arquivo é recusado (usage_error, saída 2) antes de qualquer conversão. |
--tag TAG | string | não | nenhum | De um a 32 letras ou dígitos, correspondendo a ^[A-Za-z0-9]{1,32}$. Hífens são rejeitados. Uma tag é o que torna media list --tag TAG um mapa confiável de nome de arquivo para id. |
--folder ID | string | não | raiz da biblioteca | Uma pasta de mídia mfd_ existente, verificada antes de qualquer trabalho começar. O arquivo cai nela quando está pronto, nada é movido depois, e data.folder_id a reporta. Funciona com --no-wait. Um uploader deve indicar uma das suas pastas; veja Uploaders. |
--no-wait | boolean | não | desligado | Retornar assim que o commit for aceito. O objeto ainda não está pronto; finalize com operations wait. |
--poll-ms MS | integer | não | 1000 | Intervalo entre pesquisas de operação enquanto aguarda. |
--timeout MS | integer | não | 120000 | Prazo para a espera. Também limita cada solicitação subjacente. |
--no-transcode | boolean | não | desligado | Envie os bytes da fonte sem alterações. ffmpeg, ffprobe e cwebp não são executados. O arquivo já deve ser um PNG, JPEG, WebP, GIF, MP4, WebM ou MP3, e WebP sem perdas ainda é rejeitado. Não pode ser combinado com --codec, --max-fps, --max-edge, --webp-quality, --preset ou --no-audio. |
--codec | string | não | h264 | h264 ou hevc. Use hevc somente quando todas as telas que reproduzirão o clipe forem Players nativos. |
--max-fps N | number | não | 30 | Taxa constante de quadros de saída. Todo vídeo é codificado exatamente nessa taxa, independentemente da taxa de origem, para que clipes consecutivos nunca mudem de taxa. Maior que 0 e no máximo 240. |
--max-edge PIXELS | integer | não | 3840 | Limite aplicado a cada borda, de 16 a 3840. A proporção é preservada e uma fonte menor nunca é ampliada. |
--webp-quality | integer | não | 90 | Qualidade da imagem estática para codificação WebP, de 1 a 100. |
--preset | string | não | não definido | signage-1080p30 ou signage-4k30. Tamanho de vídeo orientado e constante de 30 fps. --max-edge e --max-fps podem ajustar um preset, mas não ampliá-lo. Apenas vídeo; não pode combinar com --no-transcode. |
--no-audio | boolean | não | desligado | Omitir a faixa de áudio da entrega de vídeo. Apenas vídeo; não pode ser combinado com --no-transcode. |
--no-progress | boolean | não | desligado | Não emitir saída de progresso. O progresso sempre vai para stderr; stdout permanece reservado para o único envelope de resultado. |
screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoopO vídeo se torna um MP4: perfil High H.264 no nível 4.2, 5.1 ou 5.2, o mais baixo que se ajuste ao tamanho e à taxa, ou perfil Main H.265 no nível 5.1 ou 5.2 com --codec hevc, em yuv420p marcado Rec. 709, com no máximo 3840 por 2160 pixels por quadro. Uma fonte HDR é mapeada para Rec. 709. Áudio, quando presente na fonte, é AAC a 192 kbit/s, 48 kHz, estéreo.
Imagens estáticas tornam-se WebP com perdas na qualidade 90, mantendo alfa onde a fonte tem. Fonte animada repete para sempre. WebP que já cabe no limite de tamanho é passado sem reencodificação.
Áudio vira MP3 para trilha sonora da playlist. Fonte MP3 é enviada sem alteração; fontes WAV, AAC, M4A, OGG e FLAC são convertidas para MP3 128 kb/s, que precisa de uma build ffmpeg com libmp3lame. Uma faixa dura de 1 segundo a 3 horas. playlist init transforma entradas de áudio em faixas de trilha sonora em vez de páginas. O objeto pronto é um objeto de mídia audio com duração. Não pode ser colocado numa página; nomeie na playlist audio trilha sonora em vez disso.
O id do objeto pronto é data.media_id. O mesmo valor é data.id e data.operation.result.media_id. Esse id é o que um seletor de playlist usa.
Uma mídia pronta com os mesmos bytes, nome de arquivo e tag é retornada em vez de ser enviada de novo (data.reused é true), então repetir um upload interrompido retorna o ID da mídia. data.timing informa milissegundos por etapa: prepare_ms (conversão e hash), declare_ms, transfer_ms, commit_ms e processing_ms (até ficar pronta, tão fino quanto --poll-ms; ausente com --no-wait).
Um nome de arquivo com pouca informação como video.mp4 adiciona um aviso consultivo generic_filename ao envelope. O upload ainda é bem-sucedido e o CLI nunca renomeia o arquivo; escolha o nome antes de executar o comando.
A conversão executa ffmpeg e ffprobe de PATH, ou dos caminhos absolutos em SCREENRIG_FFMPEG e SCREENRIG_FFPROBE. Imagens fixas preferem o codificador ffmpeg libwebp e recorrem a cwebp em PATH ou SCREENRIG_CWEBP. Execute doctor antes do primeiro upload de uma sessão.
--preset signage-1080p30 limita a borda longa a 1920, a borda curta a 1080, e a taxa a 30 fps constante. signage-4k30 limita a borda longa a 3840, a borda curta a 2160, e a taxa a 30 fps constante. Ambos funcionam com conteúdo paisagem, retrato e quadrado. --no-audio omite codificação de áudio para clipes silenciosos. Essas opções aplicam-se apenas a vídeo.
screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audioscreenrig media upload ./menu.png --folder mfd_01EXAMPLEFOLDER000000000media upload-batch --folder coloca cada item enviado na pasta da mesma forma.
Uma imagem ou vídeo pode ter até 16383 pixels de largura ou altura e 67.108.864 pixels (8192 por 8192) em um quadro; um maior é recusado com invalid_request. A conversão padrão ajusta cada lado a 3840 pixels, então envie um master ultralargo como 9216 por 2160 ou 12000 por 540 com --no-transcode. Um upload de vídeo pode ter no máximo o maior upload de vídeo do plano do projeto, que project capabilities informa como media_video_bytes (veja Precificação); um vídeo maior é recusado antes de ser lido, então reduza o clipe primeiro. A CLI codifica vídeo com qualidade fixa, então um vídeo longo ainda pode exceder o limite após a codificação e então é recusado; com --no-transcode, o próprio arquivo deve caber no limite.
Uma transferência para o armazenamento que for interrompida é tentada até 4 vezes enquanto a URL de upload for válida. Se ainda falhar, o erro informa o operation_id do upload e o upload é cancelado para não ocupar armazenamento; com --idempotency-key ele é mantido para a nova execução. Execute o mesmo comando novamente.
Com acesso Propor, ou quando o projeto exige revisão para alterações do agente, um novo envio espera pela revisão de uma pessoa antes que uma tag, pasta ou seletor all seja exibido; veja Revisões.
media upload-batch#
Enviar muitos arquivos locais a partir de um manifesto, retomando de um arquivo de estado.
media upload-batch <manifest.json> [--state FILE] [--concurrency N] [--tag TAG] [--folder ID]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc]
[--max-fps N] [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<manifest.json> | caminho | sim | nenhum | { "items": [ { "path": "./a.png", "tag"?: "Lobby", "content_type"?: "image/png" } ] } com 1 a 1000 itens. Os caminhos são relativos ao arquivo de manifesto. |
--state FILE | caminho | não | arquivo privado ao lado da configuração | Um arquivo JSON 0600 indexado pelo SHA-256 dos bytes locais de cada arquivo fonte; por padrão, um arquivo por projeto, endereço da API e manifesto. Itens já presentes com um media_id são reportados como resumed. Não compartilhe um arquivo de estado entre projetos. |
--concurrency N | integer | não | 4 | Uploads paralelos, de 1 a 8. |
--no-transcode | boolean | não | desligado | Envie os bytes da fonte sem alterações, como media upload faz. Não pode ser combinado com --codec, --max-fps, --max-edge, --webp-quality, --preset ou --no-audio. |
--poll-ms MS | integer | não | 1000 | Intervalo entre pesquisas de operação enquanto aguarda. |
--timeout MS | integer | não | 120000 | Prazo para a espera. Também limita cada solicitação subjacente. |
--codec | string | não | h264 | h264 ou hevc. Use hevc somente quando todas as telas que reproduzirão o clipe forem Players nativos. |
--max-fps N | number | não | 30 | Taxa constante de quadros de saída. Todo vídeo é codificado exatamente nessa taxa, independentemente da taxa de origem, para que clipes consecutivos nunca mudem de taxa. Maior que 0 e no máximo 240. |
--max-edge PIXELS | integer | não | 3840 | Limite aplicado a cada borda, de 16 a 3840. A proporção é preservada e uma fonte menor nunca é ampliada. |
--webp-quality | integer | não | 90 | Qualidade da imagem estática para codificação WebP, de 1 a 100. |
--preset | string | não | não definido | signage-1080p30 ou signage-4k30. Tamanho de vídeo orientado e constante de 30 fps. --max-edge e --max-fps podem ajustar um preset, mas não ampliá-lo. Apenas vídeo; não pode combinar com --no-transcode. |
--no-audio | boolean | não | desligado | Omitir a faixa de áudio da entrega de vídeo. Apenas vídeo; não pode ser combinado com --no-transcode. |
--tag TAG | string | não | nenhum | Aplicado quando um item omite sua própria tag. |
--folder ID | string | não | raiz da biblioteca | Uma pasta de mídia mfd_ existente, verificada antes de qualquer trabalho começar. Cada item cai nela quando está pronto, e data.folder_id a reporta. Um uploader deve indicar uma das suas pastas. |
--no-progress | boolean | não | desligado | Não emitir saída de progresso. |
screenrig media upload-batch ./images.json --state ./upload-state.jsonO envelope carrega data.items[] na ordem do manifesto, cada um com path, source_filename, sha256, outcome (accepted ou resumed), e media_id. data.failed[] carrega itens que não foram entregues, cada um com seu path e seu problem; data.accepted, data.resumed, data.attempts, data.rate_limited, data.wait_ms e data.transfer_ms contam a execução. Um item é tentado até 8 vezes, com espera entre as tentativas, enquanto a resposta for um limite de taxa ou um erro do servidor.
Com falhas, o código de saída segue o último item com falha: 7 para um limite de taxa, 9 para um erro do servidor, 2 para um erro de uso e, nos demais casos, 8. Execute o mesmo comando novamente com o mesmo manifesto para enviar apenas o que não foi entregue.
media replace#
Substituir o arquivo de uma mídia no lugar. Seu ID, suas playlists e suas agendas continuam funcionando.
media replace <id> <file> [--expect-rev REVISION] [--note TEXT] [--content-type TYPE] [--no-wait]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
<file> | caminho | sim | nenhum | A nova imagem, clipe ou faixa de áudio. Ela deve ser do mesmo tipo que a mídia: imagem por imagem, vídeo por vídeo, áudio por áudio. Verificado antes de qualquer trabalho começar (usage_error, código de saída 2). |
--expect-rev REVISION | string | não | nenhum | Pré-condição de revisão opcional. Um valor obsoleto fornecido é revision_conflict e o upload declarado é cancelado: leia media show ID e execute o comando novamente. |
--note TEXT | string | não | nenhum | Guardada com a nova versão e mostrada à pessoa que a revisa. No máximo 280 caracteres. |
--content-type TYPE | string | não | detectado a partir dos bytes enviados | Declare o tipo de mídia você mesmo em vez de deixar o CLI detectá-lo. |
--no-wait | boolean | não | desligado | Retornar assim que a substituição for aceita. O novo arquivo ainda não está em uso; finalize com operations wait. |
--poll-ms MS | integer | não | 1000 | Intervalo entre pesquisas de operação enquanto aguarda. |
--timeout MS | integer | não | 120000 | Prazo para a espera. Também limita cada solicitação subjacente. |
--no-transcode | boolean | não | desligado | Envie os bytes da fonte sem alterações. ffmpeg, ffprobe e cwebp não são executados. O arquivo já deve ser um PNG, JPEG, WebP, GIF, MP4, WebM ou MP3, e WebP sem perdas ainda é rejeitado. Não pode ser combinado com --codec, --max-fps, --max-edge, --webp-quality, --preset ou --no-audio. |
--codec | string | não | h264 | h264 ou hevc. Use hevc somente quando todas as telas que reproduzirão o clipe forem Players nativos. |
--max-fps N | number | não | 30 | Taxa constante de quadros de saída. Todo vídeo é codificado exatamente nessa taxa, independentemente da taxa de origem, para que clipes consecutivos nunca mudem de taxa. Maior que 0 e no máximo 240. |
--max-edge PIXELS | integer | não | 3840 | Limite aplicado a cada borda, de 16 a 3840. A proporção é preservada e uma fonte menor nunca é ampliada. |
--webp-quality | integer | não | 90 | Qualidade da imagem estática para codificação WebP, de 1 a 100. |
--preset | string | não | não definido | signage-1080p30 ou signage-4k30. Tamanho de vídeo orientado e constante de 30 fps. --max-edge e --max-fps podem ajustar um preset, mas não ampliá-lo. Apenas vídeo; não pode combinar com --no-transcode. |
--no-audio | boolean | não | desligado | Omitir a faixa de áudio da entrega de vídeo. Apenas vídeo; não pode ser combinado com --no-transcode. |
--no-progress | boolean | não | desligado | Não emitir saída de progresso. O progresso sempre vai para stderr; stdout permanece reservado para o único envelope de resultado. |
screenrig media replace med_01EXAMPLEIMAGE0000000000 ./menu-v2.png
screenrig media replace med_01EXAMPLEVIDEO0000000000 ./intro.mp4 --expect-rev 3 --note "Spring cut"A mídia mantém o ID, as tags e a pasta, então cada playlist e programação que a nomeia reproduz o arquivo novo no próximo manifesto, e os seletores por tag, pasta e all também o pegam. Nada é reprogramado. O comando executa as mesmas etapas de media upload (conversão, o limite de bytes de vídeo do plano, os limites de dimensões, o limite de armazenamento do plano, a transferência assinada) e depois substitui em vez de adicionar uma mídia nova. Ele não aceita --tag nem --folder.
Por padrão, o comando aguarda o processamento. data.media_id e data.id são o ID da mídia, data.version é o número do novo arquivo em media versions, e data.revision é a nova revisão da mídia. data.warnings, data.operation, data.upload, data.transcode e os tempos são informados como em media upload, e o ID da operação está no envelope. Com --no-wait, data.operation é a operação aceita, e data.version e data.warnings estão ausentes.
Uma proporção de tela alterada é permitida. O envelope traz um aviso aspect_ratio_changed, e data.warnings[].playlists nomeia as playlists que usam a mídia, então confira como elas ficam. Um arquivo com os mesmos bytes do atual é recusado com resource_conflict (código de saída 13).
Cada arquivo anterior permanece no histórico da mídia e conta nos bytes armazenados até que sua versão seja excluída; veja media versions.
Com acesso Propose, ou quando o projeto exige revisão para alterações do agente, a substituição aguarda uma pessoa e o comando tem sucesso (código de saída 0): data.status é pending_review, data.review_id nomeia a revisão, o aviso pending_review dá a URL dela e data.next é screenrig reviews show ID. A mídia continua reproduzindo o arquivo atual até que uma pessoa aprove; avise que ela está aguardando e não repita a gravação. Uma substituição mais recente da mesma mídia substitui a que aguarda. Veja Revisões.
media versions#
Lista os arquivos que uma mídia já teve, com o arquivo em uso primeiro.
media versions <id> [--limit N] [--cursor CURSOR]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--limit N | integer | não | cada página | Ler uma página com esta quantidade de versões, de 1 a 100. |
--cursor CURSOR | string | não | nenhum | Ler a página seguinte ao data.next_cursor da página anterior. |
screenrig media versions med_01EXAMPLEIMAGE0000000000data.items tem uma entrada para cada arquivo que a mídia já teve: number, current, filename, source_filename, content_type, sha256, bytes, width, height, duration_ms, codecs, source (upload, replace, sync ou restore), note, by (tipo person, agent, client ou sync, com ID e nome), restored_from e created_at. O arquivo em uso vem primeiro (current: true), depois os demais, do mais recente ao mais antigo. A versão 1 é o primeiro upload; cada substituição, restauração ou alteração da sincronização de mídia adiciona o número seguinte.
Sem --limit e --cursor, todas as páginas são lidas e data.next_cursor é null. Com qualquer um dos dois, uma página é lida: enquanto data.next_cursor for uma string, execute o comando novamente com --cursor definido com esse valor. O acesso somente leitura basta. Os bytes de uma versão anterior permanecem armazenados e contam nos bytes armazenados do projeto até que media version delete os remova; não há limite de quantas versões são mantidas, e os bytes armazenados acima do armazenamento gratuito do plano são cobrados como qualquer outro armazenamento.
media restore#
Colocar uma versão anterior de volta em uso como nova versão.
media restore <id> --number N [--expect-rev REVISION] [--note TEXT]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--number N | integer | sim | nenhum | O número da versão a colocar de volta em uso, como media versions a lista. |
--expect-rev REVISION | string | não | nenhum | Pré-condição de revisão opcional. Um valor obsoleto fornecido é revision_conflict: leia media show ID e execute o comando novamente. |
--note TEXT | string | não | nenhum | Guardada com a nova versão e mostrada à pessoa que a revisa. No máximo 280 caracteres. |
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2 --expect-rev 5 --note "Back to the winter menu"A mídia mantém seu ID e passa para uma nova revisão, e cada playlist e agenda que a nomeia reproduz esse arquivo novamente. A versão que ela copia permanece no histórico e compartilha seus bytes; a nova versão conta nos bytes armazenados como qualquer outra. data.media é a mídia e data.warnings traz aspect_ratio_changed, que nomeia as playlists que usam a mídia, quando o arquivo restaurado tem outra proporção de tela.
A versão em uso não pode ser restaurada (resource_conflict, código de saída 5), e uma versão desconhecida é not_found (código de saída 4). Com acesso Propose, ou quando o projeto exige revisão para alterações do agente, a restauração aguarda uma pessoa e o comando tem sucesso (código de saída 0): data.status é pending_review com data.review, o aviso pending_review dá a URL dela e data.next é screenrig reviews show ID. A mídia continua reproduzindo o arquivo atual até que uma pessoa aprove, então não repita a gravação.
media version delete#
Excluir uma versão anterior e seus bytes armazenados.
media version delete <id> --number N| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--number N | integer | sim | nenhum | O número da versão a excluir, como media versions a lista. |
screenrig media version delete med_01EXAMPLEIMAGE0000000000 --number 2O registro da versão some e seus bytes saem imediatamente dos bytes armazenados do projeto. O objeto armazenado é removido após 24 horas, a menos que outra versão ou o arquivo em uso contenha o mesmo arquivo. Uma versão excluída não pode ser restaurada. A versão em uso não pode ser excluída, e nenhuma versão pode ser excluída enquanto uma substituição da mídia aguarda revisão; ambos são resource_conflict (código de saída 5), e media versions ID mostra qual versão está em uso. Uma versão desconhecida é not_found (código de saída 4). Excluir exige acesso Manage: uma credencial Propose é recusada com insufficient_access, e a exclusão nunca é proposta para revisão.
media show#
Leia um objeto de mídia, incluindo sua revisão atual.
media show <id>| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
screenrig media show med_01EXAMPLEIMAGE0000000000media download#
Escreva uma versão armazenada no disco para inspeção. Nunca imprima os bytes.
media download <id> [--output FILE]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--output FILE | caminho | não | ./<id>.<ext> no diretório atual | Um caminho de arquivo, não um diretório. Um arquivo existente é sobrescrito. A extensão segue o tipo de conteúdo. |
screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webpA resposta relata media_id, path, bytes, sha256, content_type, primitive, filename, source_filename opcional e width / height. Ela nunca traz pixels. Use-a para conferir uma imagem antes que ela vá para a tela.
media list#
Listar objetos de mídia, opcionalmente filtrados por tag, primitivo e pasta.
media list [--tag TAG] [--primitive image|video|audio] [--folder ID|root] [--library]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
--tag TAG | string | não | nenhum | Corresponder ^[A-Za-z0-9]{1,32}$. Objetos sem tag são omitidos sempre que este filtro estiver presente. |
--primitive | string | não | todos | image, video ou audio. Restringe a listagem a stills, clipes ou faixas de trilha sonora. |
--folder ID|root | string | não | toda pasta | Só arquivos diretamente dentro desta pasta mfd_, não suas subpastas, ou com root apenas arquivos na raiz da biblioteca. A API aplica o filtro. |
--library | boolean | não | desligado | Lista, em vez disso, as mídias da Biblioteca da organização, somente leitura: as linhas trazem library: true. Use os IDs delas nas páginas da playlist; altere-as apenas no projeto Biblioteca. |
screenrig media list --tag LobbyLoop --primitive video
screenrig media list --folder mfd_01EXAMPLEFOLDER000000000
screenrig media list --libraryCada linha carrega folder_id, que está ausente na raiz da biblioteca.
media selector-preview#
Pré-visualizar quais arquivos prontos um seletor de mídia dinâmico encontra agora, sem publicar uma playlist nem avançar um Player.
media selector-preview <selector.json> --primitive image|video [--rect WxH] [--timezone IANA]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<selector.json> | caminho | sim | nenhum | Um arquivo JSON com um seletor de mídia all, tag ou folder, ou - para stdin. Uma tag com token de tela não pode ser pré-visualizada. |
--primitive | string | sim | nenhum | image ou video: o tipo de arquivo que o seletor encontra. |
--rect WxH | string | com fit: "aspect" | nenhum | O tamanho do retângulo do primitivo, como 1080x1920, com ambos os números maiores que 0. |
--timezone IANA | string | não | UTC | O fuso horário em que as regras de disponibilidade dos arquivos são lidas, como America/New_York. |
screenrig media selector-preview selector.json --primitive video
screenrig media selector-preview selector.json --primitive image --timezone America/New_YorkAs chaves do seletor (order, batch_size, one_at_a_time, weights e fit) estão descritas em Filtrar tags e lotes de reprodução e Rotação ponderada e ajuste de proporção.
A resposta traz matched_count, os candidates ordenados por nome de arquivo (media_id, filename, tags, width, height), o selector normalizado e, em excluded, os arquivos deixados de fora com o reason: aspect_mismatch para fit: "aspect", e outside_window para um arquivo cuja regra de disponibilidade não vale agora. Com order: "weighted", cada candidato traz weight e share_percent, e cycle é o número de reproduções após as quais cada item tocou exatamente o seu peso. Mais de 1024 correspondências resulta em invalid_request. Acesso de leitura basta. A pré-visualização lê o projeto autenticado, nunca avança um cursor nem altera um manifesto, e uma mudança no catálogo depois dela é aplicada no próximo limite de loop de cada Player.
media update#
Substituir ou limpar as tags de um objeto. A regra de disponibilidade dele é definida com media availability.
media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--tag TAG | string | um dos três | nenhum | A tag de substituição, de uma a 32 letras ou dígitos. Ela se torna a única tag do objeto. |
--tags TAG1,TAG2 | string | um dos três | nenhum | O conjunto de tags de substituição: de 1 a 32 tags únicas separadas por vírgulas, cada uma de uma a 32 letras ou dígitos. |
--clear-tag | boolean | um dos três | desligado | Remove todas as tags e deixa o objeto sem marcação. |
--expect-rev REVISION | string | não | nenhum | Pré-condição opcional de revisão. Omitir para escrever o recurso atual. Um valor obsoleto fornecido é revision_conflict: buscar novamente, reaplicar, tentar novamente. |
screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop
screenrig media update med_01EXAMPLEIMAGE0000000000 --tags Summer,DrinksCom acesso Propor, ou quando o projeto exige revisão para alterações do agente, retagging de mídia aprovada responde ok com o aviso media_review_pending: as telas continuam exibindo com suas tags aprovadas até que uma pessoa aprove a alteração, e uma rejeição restaura as tags. A revisão aparece em reviews list em segundos; um retag que não altera nenhuma playlist aprovada nem playlist aguardando revisão aplica-se sozinho. Veja Revisões.
media availability#
Define ou limpa quando os seletores dinâmicos podem escolher um arquivo.
media availability <id> (--file FILE | --clear) [--expect-rev REVISION]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--file FILE | caminho | um dos dois | nenhum | Uma regra de disponibilidade em JSON, ou - para stdin. |
--clear | boolean | um dos dois | desligado | Remove a regra; o arquivo fica sempre disponível. |
--expect-rev REVISION | string | não | revisão atual | Pré-condição opcional de revisão. Se omitida, o comando lê primeiro a revisão atual da mídia. Um valor obsoleto fornecido é revision_conflict: buscar novamente, reaplicar, tentar novamente. |
screenrig media availability med_01EXAMPLEIMAGE0000000000 --file rule.jsonOs membros e o comportamento da regra estão em Disponibilidade de mídia. Um arquivo que aguarda a revisão de uma pessoa é recusado com media_pending_review: decida primeiro essa revisão.
media delete#
Excluir um objeto de mídia.
media delete <id> [--expect-rev REVISION]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id do objeto med_. |
--expect-rev REVISION | string | não | nenhum | Pré-condição opcional de revisão. Omitir para escrever o recurso atual. Um valor obsoleto fornecido é revision_conflict: buscar novamente, reaplicar, tentar novamente. |
screenrig media delete med_01EXAMPLEIMAGE0000000000media move#
Mover arquivos e pastas de mídia para uma pasta, ou de volta para a raiz da biblioteca.
media move <id>... (--folder ID | --root)| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id>... | string | sim | nenhum | Um ou mais IDs de arquivo med_ e IDs de pasta mfd_, no máximo 1000 no total. |
--folder ID | string | um dos dois | nenhum | A pasta de destino mfd_. |
--root | boolean | um dos dois | desligado | Mover para a raiz da biblioteca. |
screenrig media move med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --folder mfd_01EXAMPLEFOLDER000000000
screenrig media move mfd_01EXAMPLEFOLDER000000000 --rootA movimentação é uma solicitação tudo ou nada. Uma pasta não pode se mover para dentro de si mesma ou de uma pasta dentro dela, e pastas aninham no máximo 10 níveis. Itens já no destino permanecem como estão. data.media e data.folders contam o que foi movido.
Mover arquivos altera o que os seletores by:folder das suas pastas antiga e nova reproduzem, a partir da resolução do próximo seletor de cada tela; mover uma pasta não altera os arquivos próprios de nenhuma pasta. Sob Propor acesso, ou quando o projeto requer revisão para mudanças de agente, cada arquivo movido espera a revisão de uma pessoa (reviews list) e playlists aprovadas continuam a reproduzi-lo pela pasta com que foi aprovado; veja Revisões.
media folder list#
Listar as pastas de mídia do projeto.
media folder list [--library]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
--library | boolean | não | desligado | Lista, em vez disso, as pastas da Biblioteca da organização, somente leitura: as linhas trazem library: true, e um seletor by:folder pode nomear uma para reproduzir seus arquivos. |
screenrig media folder list
screenrig media folder list --libraryRetorna todas as pastas do projeto, no máximo 1000, ordenadas por nome: data.items com id, name, parent_id (null na raiz da biblioteca) e revision. Construa a árvore a partir de parent_id. A pasta de um arquivo é folder_id em media list e media show; está ausente na raiz da biblioteca.
media folder show#
Leia uma pasta de mídia.
media folder show <id>| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id da pasta mfd_. |
screenrig media folder show mfd_01EXAMPLEFOLDER000000000O envelope carrega o name, parent_id e revision da pasta.
media folder create#
Criar uma pasta de mídia na raiz da biblioteca ou dentro de outra pasta.
media folder create --name NAME [--parent ID]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
--name NAME | string | sim | nenhum | 1 a 100 caracteres, aparados. Nomes podem se repetir. |
--parent ID | string | não | raiz da biblioteca | A pasta mfd_ para criá-la. |
screenrig media folder create --name Menus
screenrig media folder create --name Lunch --parent mfd_01EXAMPLEFOLDER000000000Uma organização mantém no máximo 1000 pastas em todos os seus projetos, aninhadas em até 10 níveis. Uma playlist toca os arquivos de uma pasta com um seletor by:folder.
media folder update#
Renomear uma pasta de mídia ou movê-la com tudo dentro para outra pasta.
media folder update <id> [--name NAME] [--parent ID | --root] [--expect-rev REVISION]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id da pasta mfd_. |
--name NAME | string | pelo menos um de --name, --parent, --root | inalterado | O novo nome, de 1 a 100 caracteres. |
--parent ID | string | pelo menos um de --name, --parent, --root | inalterado | Mover a pasta, com tudo dentro, para esta pasta mfd_. Não com --root. |
--root | boolean | pelo menos um de --name, --parent, --root | desligado | Mover a pasta para a raiz da biblioteca. Não com --parent. |
--expect-rev REVISION | string | não | nenhum | Pré-condição opcional de revisão. Omitir para escrever o recurso atual. Um valor obsoleto fornecido é revision_conflict: buscar novamente, reaplicar, tentar novamente. |
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --name Archive
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --rootUma pasta não pode se mover para dentro de si mesma ou de uma pasta dentro dela, e uma movimentação deve manter todas as pastas dentro de 10 níveis. Enviar os valores atuais é uma operação sem efeito.
media folder delete#
Excluir uma pasta de mídia. Seus arquivos e pastas sobem um nível.
media folder delete <id> [--expect-rev REVISION]| Parâmetro | Tipo | Obrigatório | Padrão | Notas |
|---|---|---|---|---|
<id> | string | sim | nenhum | O id da pasta mfd_. |
--expect-rev REVISION | string | não | nenhum | Pré-condição opcional de revisão. Omitir para escrever o recurso atual. Um valor obsoleto fornecido é revision_conflict: buscar novamente, reaplicar, tentar novamente. |
screenrig media folder delete mfd_01EXAMPLEFOLDER000000000Exclui apenas a pasta. Seus arquivos e pastas sobem para o pai, ou para a raiz da biblioteca quando não tem pai. Um seletor by:folder que a nomeia não corresponde a nada, então redirecione essas playlists primeiro.
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.
Um seletor folder, { "by": "folder", "folder_id": "mfd_…" }, reproduz os arquivos prontos diretamente dentro de uma pasta de mídia e nenhum de suas subpastas; media folder list mostra os ids. Ele aceita os mesmos order, one_at_a_time e batch_size que all e tag, e excluir uma pasta move seus arquivos um nível acima e deixa o seletor vazio.
O conjunto de candidatos contém até 1.024 mídias prontas por seletor, com 1.024 referências de mídia em todo o snapshot do loop completo. Uma gravação conta cada seletor all, tag ou folder como 32 dessas referências e um seletor ids pelo seu comprimento. Uma correspondência maior retorna um erro; restrinja 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 a passagem restante. one_at_a_time: true reproduz um item por aparição e permite apenas um tamanho de lote omitido ou batch_size: 1. Em páginas de duração, de aplicativo e audio_end, todo seletor all, tag, folder e ids com vários ids exige one_at_a_time: true, e dwell_ms é recusado. Imagens em media_end também exigem dwell_ms; vídeos não podem se repetir 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 e embaralha uma vez um seletor random. 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. A rotação ponderada é um recurso do Plus: sem ele, uma gravação que define um peso que o item ainda não tem recebe feature_not_in_plan, enquanto a rotação igual, manter os pesos salvos e removê-los continuam liberados. Todo Player reproduz a ordem ponderada. Um Player que não declara a capacidade de host selector.weighted recebe random, 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 arquivo de um seletor ponderado e, com fit: aspect, lista os arquivos que deixa de fora; 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. Um token pode ficar ao lado de letras e dígitos em um modelo de até 128 caracteres. 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:
| Token | Valor |
|---|---|
{screen.id} | O identificador da tela sem seu prefixo scr_. |
{screen.name} | O nome da tela. |
{screen.timezone} | O fuso horário IANA efetivo da tela: sua substituição, senão o fuso que seu Player informa, senão UTC. |
{screen.field.NAME} | O campo NAME da tela, de 1 a 32 letras minúsculas, dígitos ou sublinhados. |
{screen.location.lat}, {screen.location.lon} | Sua localização em graus decimais. |
{screen.location.name}, {screen.location.address} | Seu nome de lugar e endereço. |
{
"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, os params preenchidos, no máximo 4096 caracteres juntos depois de codificados em percentual, chegam a ele em context.params em todo Player (SDK). O app web do Player e os Players que o executam (Samsung Tizen, BrightSign, LG webOS e Vega) também anexam cada um ao endereço de lançamento depois de ticket, codificado em percentual, de modo que o aplicativo pode ler location.search. 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.…}.
As primitivas de aplicativo de uma mesma playlist que fixam a mesma versão carregam os mesmos params.
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. Sem --expect-rev, o comando lê primeiro a revisão atual da mídia. Um arquivo que aguarda a revisão de uma pessoa é recusado com media_pending_review.
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), com até 16 windows, 16 entradas monthly, 100 dates e 100 datas except. 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. media selector-preview com --timezone ZONE (UTC por padrão) lê as regras nesse fuso e lista em excluded os arquivos fora da regra naquele momento, com o motivo outside_window.