API HTTP do LDSperimetral
Versão: 1.58.1
Última atualização: 2026-11-12
Esta referência descreve os serviços implementados de controle do player e de medição onTV. Todos os exemplos são ilustrativos.
Índice
- Configuração e acesso
- Requisições e respostas
- Rotas do player
- Parâmetros
- Dados do player
- Rotas e dados do onTV
- Exemplos
- Limitações
Configuração e acesso
Utilize uma instalação funcional do LDSperimetral no Windows com o seu tempo de execução .NET Framework 4.7.2 e a configuração normal do player. A aplicação deve estar em execução. A API é hospedada pela própria aplicação, e não por um servidor separado.
Na janela de configuração do terminal, ative o controle remoto do player para o serviço do player. Ative o medidor onTV separadamente para o serviço de estatísticas. Salve e aplique a configuração do terminal. A janela rejeita a mesma porta utilizada pela porta de rede de sincronização. As configurações armazenadas correspondentes em config/terminals.xml são remote_player_enabled, on_tv_meter_enabled e port. Ambos os sinalizadores de ativação têm como padrão o valor falso (false). O padrão no código para port é 8083; uma instalação existente pode utilizar outra porta.
| Serviço | URL Base |
|---|---|
| Player | http://HOST:PORT/ws/remoteplayer/ |
| Estatísticas onTV | http://HOST:PORT/ws/statsmeter/ |
| Interface de navegador onTV | http://HOST:PORT/ontvmeter |
Substitua HOST pelo endereço do computador do player e PORT pela porta HTTP configurada. Utilize 127.0.0.1 apenas a partir desse computador. O host é vinculado a http://0.0.0.0:PORT/; este não é um destino de cliente. Permissões de URL do Windows, regras de firewall e acessibilidade de rede podem afetar o acesso. A inicialização pode solicitar permissão para abrir a porta TCP do firewall e conceder uma reserva de URL do Windows. Siga os avisos da aplicação, incluindo uma reinicialização quando solicitada.
O serviço utiliza HTTP simples e um WebHttpBinding padrão. Nenhuma chave de API, login, autorização por comando ou lista de permissões de IP de cliente é implementada nestes serviços. Clientes acessíveis podem emitir comandos de reprodução e medição. Restrinja o acesso à rede a clientes confiáveis. As reservas de URL do Windows autorizam o processo do servidor a escutar; elas não autenticam os chamadores da API. Nenhuma configuração de HTTPS ou CORS é fornecida por este host. O acesso de origens cruzadas (cross-origin) pelo navegador não é uma interface garantida.
Requisições e respostas
Todas as rotas abaixo utilizam GET, incluindo comandos que alteram o estado. Acrescente cada rota à sua URL base de serviço. Nenhum corpo de requisição ou parâmetro de consulta é declarado. Os espaços reservados entre chaves são segmentos de caminho obrigatórios, a menos que a rota descreva explicitamente o caractere curinga de parada de sobreposição. Não envie as chaves literalmente.
As respostas utilizam serialização JSON do WCF e um objeto comum:
| Campo JSON | Tipo | Significado |
|---|---|---|
status | inteiro | Status da aplicação conforme a tabela abaixo. |
message | string ou nulo | Texto de diagnóstico; não é um identificador estável. |
result | valor específico da rota | Booleano, string, objeto, array ou nulo. |
| Valor | Identificador | Significado |
|---|---|---|
0 | OK | Nenhum erro de aplicação relatado. |
1 | COUNTER_NOT_EXIST | Definido na enumeração compartilhada; não retornado explicitamente por estas rotas. |
2 | TIMER_NOT_EXIST | Definido na enumeração compartilhada; não retornado explicitamente por estas rotas. |
3 | INTERNAL_ERROR | O processamento da requisição falhou. |
4 | PLAYLIST_NOT_FOUND | Nenhuma playlist disponível correspondeu. |
5 | INVALID_ARGUMENT | Índice de sequência inválido, início de playlist vazio ou brilho não inteiro. |
6 | SEQUENCE_NOT_FOUND | Nenhuma sobreposição disponível correspondeu. |
7 | SERVICE_NOT_READY | Controle do player indisponível ou encerrando, ou controles de brilho indisponíveis. |
Os erros da aplicação são retornados neste invólucro sem alterar explicitamente o status HTTP. Um erro de aplicação serializado normalmente permanece, portanto, uma resposta de sucesso HTTP. Inspecione sempre o status e, em seguida, o result esperado. Um erro de transporte ou de roteamento WCF pode ter um corpo diferente e não deve ser analisado como um invólucro garantido. Os testes esperam o código HTTP 404 para uma rota desconhecida e 405 para um método não suportado; essas expectativas não foram verificadas em um host em execução para esta referência.
Para comandos booleanos, status: 0 e result: true significam que o caminho do comando foi processado. Eles não comprovam uma saída audiovisual bem-sucedida ou a conclusão de uma transição. Alguns métodos secundários capturam erros ou não fazem nada quando nenhuma renderização existe. Consulte get_reproduction_state após um comando e aguarde o estado pretendido com um tempo limite (timeout) definido pelo cliente. Não há ID de comando, endpoint de conclusão, notificação por push ou prazo de transição especificado. Não envie repetidamente um comando enquanto aguarda o seu efeito.
Exceto para ping, as operações do player passam pelo despachante da janela de controle quando disponível. Isso serializa o acesso de controle na thread da interface do usuário (UI thread), mas não torna requisições HTTP separadas uma transação atômica. As operações de estatísticas não utilizam este auxiliar de despacho do player.
Rotas do player
Todos os caminhos nesta tabela são relativos a /ws/remoteplayer/.
| Rota GET | Resultado bem-sucedido | Efeito ou consulta |
|---|---|---|
ping | booleano true | Verifica se o serviço responde; não verifica a prontidão da renderização. |
get_instance_name | string | Nome da instância configurada; pode estar vazio. |
list_playlists | array de PlaylistInfo | Playlists disponíveis na ordem da coleção. |
list_playlist_sequences/{playlist_name} | array de SequenceInfo | Sequências na ordem da playlist; os índices começam em zero. |
list_overlay_sequences | array de SequenceInfo | Sequências de sobreposição disponíveis sempre no topo (always-on-top). |
get_reproduction_state | ReproductionState | Estado atual de controle e renderização. |
start_playlist/{playlist_name} | booleano | Inicia a playlist selecionada, incluindo playlists de ação rápida. Playlists vazias são rejeitadas. |
start_sequence/{playlist_name}/{sequence_number} | booleano | Inicia a sequência existente selecionada. |
start_aot_sequence/{sequence_name_or_file} | booleano | Inicia a sobreposição selecionada sempre no topo sobre o plano de fundo. |
start_aot_sequence/* | booleano | Manipulador de parada com curinga. Utilize start_aot_sequence/ para remover a sobreposição; mantenha a barra (slash) final. Não envie um asterisco literal. |
stop | booleano | Chama a operação de parada do player. Consulte o estado para confirmar se a reprodução parou. |
pause | booleano | Pausa se a renderização já não estiver pausada. |
resume | booleano | Retoma a reprodução se a renderização estiver pausada. |
pauseresume | booleano | Alterna (faz toggle) o estado de pausa da renderização. |
play_next | booleano | Inicia a próxima sequência; retorna do último para o primeiro item. Não faz nada sem uma sequência e playlist ativas. |
quick_action_exit | booleano | Solicita a saída quando a renderização estiver no modo de ação rápida; caso contrário, não faz nada. |
set_global_brightness/{brightness_tpc} | booleano | Define cada valor de matriz de brilho disponível para a porcentagem fornecida dividida por 100. Nenhuma consulta HTTP de brilho está definida. |
A rota de sobreposição nomeada é mais específica do que a com curinga. Um nome de sobreposição inexistente retorna SEQUENCE_NOT_FOUND; não se trata de uma requisição de parada. O roteamento com curinga de final vazio (empty-tail) e outros casos extremos de caminhos codificados ainda exigem validação do host.
Parâmetros
| Parâmetro | Tipo e regras |
|---|---|
playlist_name | String obrigatória. Corresponde exatamente ao nome da playlist ou ao nome base (basename) de seu arquivo de definição, incluindo a extensão. A correspondência diferencia maiúsculas de minúsculas (case-sensitive) e retorna a primeira correspondência na coleção disponível. Um caminho de definição completo não é uma chave de busca de playlist. |
sequence_number | Inteiro de 32 bits com sinal obrigatório, analisado com cultura invariante. Deve estar entre 0 e sequence_count - 1. Valores negativos, não inteiros, com estouro (overflow) e fora do intervalo retornam INVALID_ARGUMENT após a busca da playlist. Uma playlist ausente retorna PLAYLIST_NOT_FOUND primeiro. |
sequence_name_or_file | String obrigatória para o início da sobreposição. Corresponde exatamente ao nome da sobreposição, ao valor do arquivo armazenado ou ao nome base do arquivo. A correspondência diferencia maiúsculas de minúsculas e retorna a primeira correspondência. Prefira nomes ou nomes base para URLs. |
brightness_tpc | Texto de inteiro com sinal de 32 bits obrigatório. Os valores numéricos são limitados de 0 a 100 porcento. Valores não inteiros e de estouro retornam INVALID_ARGUMENT. A análise utiliza a cultura de inteiros padrão do servidor. Utilize dígitos decimais simples com um sinal opcional. |
Codifique em porcentagem (percent-encode) cada segmento de caminho de string como UTF-8. Por exemplo, Demo Show torna-se Demo%20Show; codifique um + literal como %2B, # como %23, ? como %3F e % como %25. Não codifique os separadores entre os segmentos da rota. Os auxiliares de URL utilizam Uri.EscapeDataString para referências de inicialização. Barras codificadas, barras invertidas e caminhos completos de sistema de arquivos podem ser afetados pela pilha HTTP do Windows e não são verificados aqui. Prefira um nome exclusivo ou nome base sem separadores de caminho. Segmentos obrigatórios ausentes podem causar falha no roteamento WCF antes da validação da aplicação.
Dados do player
Os nomes dos campos abaixo são nomes exatos de contrato JSON. A ordem das propriedades do objeto não é significativa. Os campos de arquivo contêm referências armazenadas e podem expor informações do sistema de arquivos; não assuma que sejam URLs de download públicas.
| Campo de PlaylistInfo | Tipo e significado |
|---|---|
name | string; nome da playlist. |
filename | string; referência do arquivo de definição da playlist armazenado. |
is_quick_action | booleano; sinalizador de interrupção da playlist. |
has_button | booleano; sinalizador de botão de acesso rápido. |
button_color | objeto; membros de cores WCF A, B, G, R (canais de bytes, 0–255) e ScA, ScB, ScG, ScR (canais scRGB de ponto flutuante). Isto não é uma string CSS. |
sequence_count | inteiro; número de sequências. |
| Campo de SequenceInfo | Tipo e significado |
|---|---|
name | string; nome da sequência. |
filename | string; referência do arquivo de sequência armazenado. |
is_on_top | booleano; verdadeiro para listagens de sobreposição, falso para listagens de sequências de playlist. |
| Campo de ReproductionState | Tipo e significado |
|---|---|
is_playing | booleano; existe uma playlist ativa. Não estabelece saída visível. |
is_paused | booleano; controla o estado de pausa. |
is_render_active | booleano; sinalizador de renderização ativa, falso sem uma renderização. |
is_quickaction | booleano; existem uma playlist ativa e uma renderização no modo de ação rápida. |
current_playlist | string; nome da playlist ativa, caso contrário, vazio. |
current_playlist_file | string; referência de definição da playlist ativa, caso contrário, vazio. |
current_sequence | string; nome da sequência ativa, caso contrário, vazio. |
current_sequence_index | inteiro; índice da sequência ativa baseado em zero, caso contrário -1. |
current_overlay_sequence_name | string; nome da sobreposição ativa, caso contrário, vazio. |
current_overlay_sequence_file | string; referência do arquivo de sobreposição ativo, caso contrário, vazio. |
current_sequence_elapsed_time | string; contador de tempo decorrido da sequência multiplicado por 1000, em milissegundos. |
current_sequence_total_time | string; duração da sequência em milissegundos, truncada em direção a zero. |
Os valores de tempo são strings JSON, e não números ou intervalos de tempo formatados. Ambos os campos de tempo são "0" sem uma sequência ativa. A interpolação deles utiliza a cultura do servidor; não assuma um separador decimal invariante ou precisão de medição em milissegundos. Valores de arquivo/nome copiados do modelo podem ser nulos. Um erro de aplicação pode retornar resultados nulos, vazios ou parcialmente preenchidos; verifique o status antes de utilizá-los.
Rotas e dados do onTV
Todos os caminhos nesta tabela são relativos a /ws/statsmeter/. Mantenha a grafia mesures exatamente como exibido.
| Rota GET | Resultado bem-sucedido | Efeito ou consulta |
|---|---|---|
start_on_tv_interval | OnTVInterval | Abre um intervalo de medição; um intervalo já aberto é mantido. |
stop_on_tv_interval | OnTVInterval | Fecha o último intervalo se estiver aberto. |
state_on_tv_interval | OnTVInterval | Retorna o último intervalo, incluindo um intervalo fechado. |
get_all_intervals_on_tv | array de OnTVInterval | Retorna a lista de intervalos do medidor de renderização. Nenhuma paginação ou filtro de data é declarado. |
get_mesures_statistics | TransmissionStatistics | Conta e totaliza os intervalos concluídos. |
Estes comandos marcam períodos de medição. Eles não iniciam nem param a reprodução da playlist e não detectam um sinal de transmissão. O controlador retorna um intervalo padrão, ou uma lista vazia para a operação de listagem, quando nenhuma renderização existe. Uma renderização sem um medidor de estatísticas pode retornar nulo; iniciar e parar encontrarão então a desreferenciação de log do serviço e relatarão um erro interno. Esta pode ser uma resposta OK sem uma medição real.
| Campo de OnTVInterval | Tipo e significado |
|---|---|
begin | string DateTime JSON do WCF; início do intervalo. |
end | string DateTime JSON do WCF; fim do intervalo. |
O marcador não definido é uma data com o ano 1970, inicializada como 1 de janeiro de 1970. Um intervalo aberto tem um fim não definido. Nenhum intervalo gravado produz um objeto padrão com ambas as datas não definidas. Uma parada repetida deixa um intervalo fechado inalterado. As datas originam-se de DateTime.Now no servidor. O WCF utiliza a representação /Date(milliseconds[+or-offset])/, com possível escape de barra (slash) em JSON; não é um contrato ISO 8601. O deslocamento opcional e o tratamento de DateTime local/não especificado devem ser verificados no host implantado. Não interprete o valor sentinela como um carimbo de data/hora (timestamp) medido real.
| Campo de TransmissionStatistics | Tipo e significado |
|---|---|
intervals_recorded | inteiro; contagem onde os anos de início e fim diferem de 1970. |
total_seconds_in_tv | segundos inteiros; soma dos milissegundos do intervalo concluído, convertida em um inteiro de 32 bits, depois dividida por 1000 e arredondada com Math.Round. Intervalos abertos são excluídos. |
O acúmulo de milissegundos utiliza uma conversão de inteiro de 32 bits antes do arredondamento. Históricos longos podem exceder esse intervalo. Não trate isto como um contador de duração de precisão ilimitada ou como um histórico vitalício garantido entre reinicializações. As capturas de estatísticas relatam INTERNAL_ERROR; a mensagem delas pode permanecer nula.
Exemplos
Todas as requisições e valores JSON nesta seção são ilustrativos. O host, os nomes e as referências de arquivos são espaços reservados sem dados privados. As respostas são invólucros completos, a menos que descrito o contrário. A ordem das propriedades e os espaços em branco do JSON podem diferir.
Verifique a disponibilidade a partir do computador do player quando a porta configurada for 8083:
curl "http://127.0.0.1:8083/ws/remoteplayer/ping"
{"message":null,"result":true,"status":0}
Liste as sequências em uma playlist disponível chamada Demo Show:
curl "http://127.0.0.1:8083/ws/remoteplayer/list_playlist_sequences/Demo%20Show"
{"message":null,"result":[{"filename":"demo.sequence","is_on_top":false,"name":"Opening"}],"status":0}
Inicie sua primeira sequência e, em seguida, consulte o estado. Estas são duas requisições separadas:
curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/0"
curl "http://127.0.0.1:8083/ws/remoteplayer/get_reproduction_state"
Resposta de comando ilustrativa:
{"message":null,"result":true,"status":0}
Resposta de estado ilustrativa após a transição:
{"message":null,"result":{"is_playing":true,"is_paused":false,"is_render_active":true,"is_quickaction":false,"current_playlist":"Demo Show","current_playlist_file":"demo.playlist","current_sequence":"Opening","current_sequence_index":0,"current_overlay_sequence_name":"","current_overlay_sequence_file":"","current_sequence_elapsed_time":"1000","current_sequence_total_time":"300000"},"status":0}
Um índice de sequência inválido em uma playlist existente:
curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/-1"
{"message":"Sequence index must identify an existing sequence.","result":false,"status":5}
Uma consulta de playlist ausente:
{"message":"Playlist [Missing] not found.","result":[],"status":4}
Inicie uma sobreposição chamada Demo Overlay e, em seguida, remova-a:
curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/Demo%20Overlay"
curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/"
Defina o brilho global para 50 porcento:
curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"
Abra, inspecione e feche um intervalo onTV e, em seguida, leia os totais:
curl "http://127.0.0.1:8083/ws/statsmeter/start_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/state_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/stop_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/get_mesures_statistics"
Resposta de estatísticas ilustrativa após um intervalo concluído de cinco segundos:
{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}
Limitações
Deslocamentos de data, roteamento com curinga, corpos de erro HTTP e acesso específico à implantação exigem validação na instalação de destino.
Nenhum limite de taxa (rate limit), isolamento de cliente, transação de requisição, garantia geral de idempotência ou garantia de conclusão audiovisual é implementado por esta camada de API. Os comandos utilizam GET, portanto, a visualização prévia de links (link previewing), o pré-carregamento (prefetching), o cache e as tentativas automáticas (retries) podem ser inseguros para comandos. Utilize um cliente que envie requisições apenas quando pretendido e que não reutilize respostas de consultas em cache. O código do servidor não estabelece um contrato de controle de cache.
A interface HTML do onTV, os metadados WCF e os endpoints mex são separados das operações JSON documentadas aqui. Eles não são rotas adicionais de comandos do player. Nenhuma operação de upload, edição de playlist, download de arquivo, leitura de brilho (readback) ou assinatura de eventos é declarada nestes dois contratos JSON.