API HTTP de LDSperimetral
Versión: 1.58.1
Última actualización: 2026-11-12
Esta referencia describe los servicios implementados de control del reproductor y de medición onTV. Todos los ejemplos son ilustrativos.
Contenido
- Configuración y acceso
- Peticiones y respuestas
- Rutas del reproductor
- Parámetros
- Datos del reproductor
- Rutas y datos de onTV
- Ejemplos
- Limitaciones
Configuración y acceso
Utiliza una instalación funcional de LDSperimetral en Windows con su entorno de ejecución .NET Framework 4.7.2 y la configuración normal del reproductor. La aplicación debe estar en ejecución. La API está alojada en la aplicación, no en un servidor independiente.
En la ventana de configuración de la terminal, habilita el control remoto del reproductor para el servicio del reproductor. Habilita el medidor onTV por separado para el servicio de estadísticas. Guarda y aplica la configuración de la terminal. La ventana rechaza el mismo puerto utilizado para la red de sincronización. Los ajustes almacenados correspondientes en config/terminals.xml son remote_player_enabled, on_tv_meter_enabled y port. Ambos indicadores de habilitación tienen como valor predeterminado falso (false). El valor predeterminado en el código para port es 8083; una instalación existente puede utilizar otro puerto.
| Servicio | URL base |
|---|---|
| Reproductor | http://HOST:PORT/ws/remoteplayer/ |
| Estadísticas onTV | http://HOST:PORT/ws/statsmeter/ |
| Interfaz de navegador onTV | http://HOST:PORT/ontvmeter |
Reemplaza HOST con la dirección del equipo del reproductor y PORT con su puerto HTTP configurado. Utiliza 127.0.0.1 únicamente desde ese mismo equipo. El host se enlaza a http://0.0.0.0:PORT/; este no es un destino de cliente. Los permisos de URL de Windows, las reglas del firewall y la accesibilidad de red pueden afectar el acceso. El inicio puede solicitar permiso para abrir el puerto TCP del firewall y conceder una reserva de URL en Windows. Sigue las indicaciones de la aplicación, incluido un reinicio cuando se solicite.
El servicio utiliza HTTP plano y un WebHttpBinding predeterminado. Estos servicios no implementan ninguna clave de API, inicio de sesión, autorización por comando ni lista blanca de direcciones IP de clientes. Los clientes accesibles pueden emitir comandos de reproducción y medición. Restringe el acceso de red a clientes de confianza. Las reservas de URL de Windows autorizan al proceso del servidor a escuchar; no autentican a los llamadores de la API. Este host no proporciona ninguna configuración de HTTPS ni de CORS. El acceso de origen cruzado desde el navegador no es una interfaz garantizada.
Peticiones y respuestas
Todas las rutas siguientes utilizan GET, incluidos los comandos que cambian el estado. Añade cada ruta a su URL base de servicio. No se declara ningún cuerpo de petición ni parámetro de consulta. Los marcadores de posición entre llaves son segmentos de ruta obligatorios, a menos que la ruta describa explícitamente el comodín de parada de superposición. No envíes las llaves literalmente.
Las respuestas utilizan serialización JSON de WCF y un objeto común:
| Campo JSON | Tipo | Significado |
|---|---|---|
status | entero (integer) | Estado de la aplicación según la tabla siguiente. |
message | cadena o nulo (string or null) | Texto de diagnóstico; no es un identificador estable. |
result | valor específico de la ruta | Booleano, cadena, objeto, matriz o nulo. |
| Valor | Identificador | Significado |
|---|---|---|
0 | OK | No se ha reportado ningún error de aplicación. |
1 | COUNTER_NOT_EXIST | Definido en la enumeración compartida; estas rutas no lo devuelven explícitamente. |
2 | TIMER_NOT_EXIST | Definido en la enumeración compartida; estas rutas no lo devuelven explícitamente. |
3 | INTERNAL_ERROR | El procesamiento de la petición ha fallado. |
4 | PLAYLIST_NOT_FOUND | Ninguna lista de reproducción disponible coincide. |
5 | INVALID_ARGUMENT | Índice de secuencia no válido, inicio de lista de reproducción vacío o brillo no entero. |
6 | SEQUENCE_NOT_FOUND | Ninguna superposición disponible coincide. |
7 | SERVICE_NOT_READY | Control del reproductor no disponible o cerrándose, o controles de brillo no disponibles. |
Los errores de la aplicación se devuelven en este contenedor sin cambiar explícitamente el estado HTTP. Por lo tanto, un error normal de aplicación serializado sigue siendo una respuesta de éxito HTTP. Inspecciona siempre status y luego el result esperado. Un error de transporte o de enrutamiento de WCF puede tener un cuerpo diferente y no debe analizarse como un contenedor garantizado. Las pruebas esperan un código HTTP 404 para una ruta desconocida y 405 para un método no compatible; estas expectativas no se han verificado frente a un host en ejecución para esta referencia.
Para los comandos booleanos, status: 0 y result: true significan que la ruta del comando fue procesada. No demuestran una salida audiovisual exitosa ni la finalización de una transición. Algunos métodos posteriores capturan errores o no hacen nada cuando no existe renderizado. Consulta get_reproduction_state después de un comando y espera el estado deseado con un tiempo de espera (timeout) definido por el cliente. No hay ningún ID de comando, punto de conexión de finalización, notificación push o límite de tiempo de transición especificado. No envíes un comando repetidamente mientras esperas su efecto.
Excepto para ping, las operaciones del reproductor pasan por el despachador de la ventana de control cuando está disponible. Esto serializa su acceso de control en el hilo de la interfaz de usuario (UI thread), pero no convierte las peticiones HTTP separadas en una transacción atómica. Las operaciones de estadísticas no utilizan este asistente de despacho del reproductor.
Rutas del reproductor
Todas las rutas de esta tabla son relativas a /ws/remoteplayer/.
| Ruta GET | Resultado exitoso | Efecto o consulta |
|---|---|---|
ping | booleano true | Comprueba que el servicio responde; no verifica la preparación del renderizado. |
get_instance_name | cadena | Nombre de instancia configurado; puede estar vacío. |
list_playlists | matriz de PlaylistInfo | Listas de reproducción disponibles en el orden de la colección. |
list_playlist_sequences/{playlist_name} | matriz de SequenceInfo | Secuencias en el orden de la lista de reproducción; los índices comienzan en cero. |
list_overlay_sequences | matriz de SequenceInfo | Secuencias de superposición siempre visibles (always-on-top) disponibles. |
get_reproduction_state | ReproductionState | Estado actual de control y renderizado. |
start_playlist/{playlist_name} | booleano | Inicia la lista de reproducción seleccionada, incluidas las listas de reproducción de acción rápida. Las listas vacías son rechazadas. |
start_sequence/{playlist_name}/{sequence_number} | booleano | Inicia la secuencia existente seleccionada. |
start_aot_sequence/{sequence_name_or_file} | booleano | Inicia la superposición seleccionada (siempre visible) sobre el fondo. |
start_aot_sequence/* | booleano | Controlador de parada mediante comodín. Utiliza start_aot_sequence/ para eliminar la superposición; conserva la barra diagonal final. No envíes un asterisco literal. |
stop | booleano | Llama a la operación de parada del reproductor. Consulta el estado para confirmar que la reproducción se ha detenido. |
pause | booleano | Pausa el renderizado si no está ya pausado. |
resume | booleano | Reanuda el renderizado si está pausado. |
pauseresume | booleano | Alterna el estado de pausa del renderizado. |
play_next | booleano | Inicia la siguiente secuencia; vuelve del final al principio. No hace nada si no hay una secuencia y una lista de reproducción activas. |
quick_action_exit | booleano | Solicita la salida cuando el renderizado está en modo de acción rápida; de lo contrario, no hace nada. |
set_global_brightness/{brightness_tpc} | booleano | Establece cada valor de matriz de brillo disponible al porcentaje proporcionado dividido por 100. No se define ninguna consulta HTTP de brillo. |
La ruta de superposición nombrada es más específica que el comodín. Un nombre de superposición inexistente devuelve SEQUENCE_NOT_FOUND; no es una petición de parada. El enrutamiento de comodines con sufijo vacío y otros casos extremos de rutas codificadas aún requieren validación por parte del host.
Parámetros
| Parámetro | Tipo y reglas |
|---|---|
playlist_name | Cadena obligatoria. Coincide con el nombre exacto de la lista de reproducción o con el nombre base (basename) de su archivo de definición, incluida la extensión. La coincidencia distingue entre mayúsculas y minúsculas y devuelve la primera coincidencia en la colección disponible. Una ruta de definición completa no es una clave de búsqueda de listas de reproducción. |
sequence_number | Entero con signo de 32 bits obligatorio analizado con cultura invariante. Debe estar entre 0 y sequence_count - 1. Los valores negativos, no enteros, de desbordamiento (overflow) y fuera de rango devuelven INVALID_ARGUMENT después de buscar la lista de reproducción. Una lista de reproducción faltante devuelve primero PLAYLIST_NOT_FOUND. |
sequence_name_or_file | Cadena obligatoria para iniciar una superposición. Coincide con el nombre exacto de la superposición, el valor del archivo almacenado o el nombre base del archivo. La coincidencia distingue entre mayúsculas y minúsculas y devuelve la primera coincidencia. Se prefieren los nombres o nombres base para las URL. |
brightness_tpc | Texto de entero con signo de 32 bits obligatorio. Los valores numéricos se limitan (clamped) entre 0 y 100 por ciento. Los valores no enteros y de desbordamiento devuelven INVALID_ARGUMENT. El análisis utiliza la cultura entera predeterminada del servidor. Utiliza dígitos decimales planos con un signo opcional. |
Codifica cada segmento de ruta de cadena como porcentaje UTF-8 (percent-encode). Por ejemplo, Demo Show se convierte en Demo%20Show; codifica un + literal como %2B, # como %23, ? como %3F y % como %25. No codifiques los separadores entre segmentos de ruta. Los ayudantes de URL utilizan Uri.EscapeDataString para las referencias de lanzamiento. Las barras diagonales codificadas, las barras diagonales invertidas (backslashes) y las rutas completas del sistema de archivos pueden verse afectadas por la pila HTTP de Windows y no se han verificado aquí. Se prefiere un nombre único o un nombre base sin separadores de ruta. Los segmentos obligatorios faltantes pueden hacer que el enrutamiento de WCF falle antes de la validación de la aplicación.
Datos del reproductor
Los nombres de campo a continuación son los nombres exactos del contrato JSON. El orden de las propiedades del objeto no es significativo. Los campos de archivo contienen referencias almacenadas y pueden exponer información del sistema de archivos; no asumas que son URLs de descarga públicas.
| Campo de PlaylistInfo | Tipo y significado |
|---|---|
name | cadena; nombre de la lista de reproducción. |
filename | cadena; referencia al archivo de definición de la lista de reproducción almacenado. |
is_quick_action | booleano; indicador de interrupción de la lista de reproducción. |
has_button | booleano; indicador de botón de acceso rápido. |
button_color | objeto; miembros de color WCF A, B, G, R (canales de bytes, 0–255) y ScA, ScB, ScG, ScR (canales scRGB de punto flotante). Esto no es una cadena CSS. |
sequence_count | entero; número de secuencias. |
| Campo de SequenceInfo | Tipo y significado |
|---|---|
name | cadena; nombre de la secuencia. |
filename | cadena; referencia al archivo de secuencia almacenado. |
is_on_top | booleano; verdadero (true) para listados de superposición, falso (false) para listados de secuencias de listas de reproducción. |
| Campo de ReproductionState | Tipo y significado |
|---|---|
is_playing | booleano; existe una lista de reproducción activa. No establece una salida visible. |
is_paused | booleano; estado de pausa del control. |
is_render_active | booleano; indicador de renderizado activo, falso si no hay renderizado. |
is_quickaction | booleano; existen una lista de reproducción activa y un renderizado en modo de acción rápida. |
current_playlist | cadena; nombre de la lista de reproducción activa; de lo contrario, vacío. |
current_playlist_file | cadena; referencia de definición de la lista de reproducción activa; de lo contrario, vacío. |
current_sequence | cadena; nombre de la secuencia activa; de lo contrario, vacío. |
current_sequence_index | entero; índice de la secuencia activa basado en cero; de lo contrario, -1. |
current_overlay_sequence_name | cadena; nombre de la superposición activa; de lo contrario, vacío. |
current_overlay_sequence_file | cadena; referencia del archivo de superposición activo; de lo contrario, vacío. |
current_sequence_elapsed_time | cadena; contador de tiempo transcurrido de la secuencia multiplicado por 1000, en milisegundos. |
current_sequence_total_time | cadena; duración de la secuencia en milisegundos, truncada hacia cero. |
Los valores de tiempo son cadenas JSON, no números ni intervalos de tiempo formateados. Ambos campos de tiempo son "0" cuando no hay una secuencia activa. Su interpolación utiliza la cultura del servidor; no asumas un separador decimal invariante ni una precisión de medición en milisegundos. Los valores de archivo/nombre copiados del modelo pueden ser nulos. Un error de aplicación puede devolver resultados nulos, vacíos o parcialmente poblados; comprueba status antes de usarlos.
Rutas y datos de onTV
Todas las rutas de esta tabla son relativas a /ws/statsmeter/. Mantén la ortografía mesures exactamente como se muestra.
| Ruta GET | Resultado exitoso | Efecto o consulta |
|---|---|---|
start_on_tv_interval | OnTVInterval | Abre un intervalo de medición; un intervalo ya abierto se mantiene. |
stop_on_tv_interval | OnTVInterval | Cierra el último intervalo si está abierto. |
state_on_tv_interval | OnTVInterval | Devuelve el último intervalo, incluido un intervalo cerrado. |
get_all_intervals_on_tv | matriz de OnTVInterval | Devuelve la lista de intervalos del medidor de renderizado. No se declara paginación ni filtro de fechas. |
get_mesures_statistics | TransmissionStatistics | Cuenta y totaliza los intervalos completados. |
Estos comandos marcan períodos de medición. No inician ni detienen la reproducción de listas de reproducción y no detectan una señal de emisión. El controlador devuelve un intervalo predeterminado, o una lista vacía para la operación de listado, cuando no existe renderizado. Un renderizado sin medidor de estadísticas puede devolver nulo; por lo tanto, el inicio y la parada se encontrarán con la desreferenciación de registro del servicio y reportarán un error interno. Esto puede ser una respuesta OK sin una medición real.
| Campo de OnTVInterval | Tipo y significado |
|---|---|
begin | Cadena DateTime JSON de WCF; inicio del intervalo. |
end | Cadena DateTime JSON de WCF; fin del intervalo. |
El marcador no establecido es una fecha con el año 1970, inicializada como el 1 de enero de 1970. Un intervalo abierto tiene un fin no establecido. Ningún intervalo registrado produce un objeto predeterminado con ambas fechas sin establecer. Una parada repetida deja un intervalo cerrado sin cambios. Las fechas se originan a partir de DateTime.Now en el servidor. WCF utiliza la representación /Date(milliseconds[+or-offset])/, con un posible escape de barras diagonales en JSON; no es un contrato ISO 8601. El desplazamiento opcional y el manejo de DateTime local/no especificado deben comprobarse en el host implementado. No interpretes el centinela como una marca de tiempo medida real.
| Campo de TransmissionStatistics | Tipo y significado |
|---|---|
intervals_recorded | entero; recuento donde tanto el año de inicio como el de fin difieren de 1970. |
total_seconds_in_tv | segundos enteros; suma de los milisegundos de los intervalos completados, convertida a un entero de 32 bits, luego dividida por 1000 y redondeada con Math.Round. Se excluyen los intervalos abiertos. |
La acumulación de milisegundos utiliza una conversión de entero de 32 bits antes del redondeo. Los historiales largos pueden superar ese rango. No trates esto como un contador de duración de precisión ilimitada ni como un historial de por vida garantizado entre reinicios. Las capturas de estadísticas reportan INTERNAL_ERROR; su mensaje puede permanecer nulo.
Ejemplos
Todas las peticiones y valores JSON de esta sección son ilustrativos. El host, los nombres y las referencias de archivos son marcadores de posición sin datos privados. Las respuestas son contenedores completos a menos que se describa lo contrario. El orden de las propiedades y los espacios en blanco de JSON pueden diferir.
Comprueba la disponibilidad desde el equipo del reproductor cuando el puerto configurado sea 8083:
curl "http://127.0.0.1:8083/ws/remoteplayer/ping"
{"message":null,"result":true,"status":0}
Lista las secuencias en una lista de reproducción disponible llamada 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}
Inicia su primera secuencia y luego consulta el estado. Estas son dos peticiones 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"
Respuesta de comando ilustrativa:
{"message":null,"result":true,"status":0}
Respuesta de estado ilustrativa después de la transición:
{"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}
Un índice de secuencia no válido en una lista de reproducción 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}
Una consulta de lista de reproducción faltante:
{"message":"Playlist [Missing] not found.","result":[],"status":4}
Inicia una superposición llamada Demo Overlay y luego elimínala:
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/"
Establece el brillo global al 50 por ciento:
curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"
Abre, inspecciona y cierra un intervalo onTV, y luego lee los totales:
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"
Respuesta de estadísticas ilustrativa después de un intervalo completado de cinco segundos:
{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}
Limitaciones
Los desfases de fecha, el enrutamiento con comodines, los cuerpos de error HTTP y el acceso específico a la implementación requieren validación en la instalación de destino.
Esta capa de API no implementa ningún límite de frecuencia (rate limit), aislamiento de clientes, transacción de peticiones, garantía general de idempotencia ni garantía de finalización audiovisual. Los comandos utilizan GET, por lo que la vista previa de enlaces, la recuperación anticipada (prefetching), el almacenamiento en caché y los reintentos automáticos pueden no ser seguros para los comandos. Utiliza un cliente que envíe peticiones únicamente cuando esté previsto y que no reutilice respuestas de consulta almacenadas en caché. El código del servidor no establece un contrato de control de caché.
La interfaz HTML de onTV, los metadatos de WCF y los puntos de conexión mex están separados de las operaciones JSON documentadas aquí. No son rutas adicionales de comandos del reproductor. En estos dos contratos JSON no se declara ninguna operación de subida (upload), edición de listas de reproducción, descarga de archivos, lectura de brillo ni suscripción a eventos.