API HTTP LDSperimetral
Version : 1.58.1
Dernière mise à jour : 2026-11-12
Cette référence décrit les services implémentés de contrôle du lecteur et de mesure onTV. Tous les exemples sont illustratifs.
Sommaire
- Installation et accès
- Requêtes et réponses
- Routes du lecteur
- Paramètres
- Données du lecteur
- Routes et données onTV
- Exemples
- Limitations
Installation et accès
Utilisez une installation LDSperimetral fonctionnelle sous Windows avec son environnement d'exécution .NET Framework 4.7.2 et une configuration de lecteur normale. L'application doit être en cours d'exécution. L'API est hébergée par l'application et non par un serveur séparé.
Dans la fenêtre de configuration du terminal, activez le contrôle à distance pour le service de lecture. Activez le compteur onTV séparément pour le service de statistiques. Enregistrez et appliquez la configuration du terminal. La fenêtre rejette le même port que le port réseau de synchronisation. Les paramètres stockés correspondants dans config/terminals.xml sont remote_player_enabled, on_tv_meter_enabled et port. Les deux indicateurs d'activation sont désactivés par défaut (false). La valeur par défaut dans le code pour port est 8083 ; une installation existante peut utiliser un autre port.
| Service | URL de base |
|---|---|
| Lecteur | http://HOST:PORT/ws/remoteplayer/ |
| Statistiques onTV | http://HOST:PORT/ws/statsmeter/ |
| Interface du navigateur onTV | http://HOST:PORT/ontvmeter |
Remplacez HOST par l'adresse de l'ordinateur du lecteur et PORT par son port HTTP configuré. Utilisez 127.0.0.1 uniquement depuis cet ordinateur. L'hôte se lie à http://0.0.0.0:PORT/ ; il ne s'agit pas d'une destination client. Les autorisations d'URL Windows, les règles de pare-feu et l'accessibilité réseau peuvent affecter l'accès. Le démarrage peut demander l'autorisation d'ouvrir le port de pare-feu TCP et d'accorder une réservation d'URL Windows. Suivez les invites de l'application, y compris un redémarrage si demandé.
Le service utilise du HTTP simple et un WebHttpBinding par défaut. Aucune clé d'API, connexion, autorisation par commande ou liste blanche d'adresses IP clientes n'est implémentée dans ces services. Les clients joignables peuvent émettre des commandes de lecture et de mesure. Restreignez l'accès réseau aux clients de confiance. Les réservations d'URL Windows autorisent le processus serveur à écouter ; elles n'authentifient pas les appelants de l'API. Aucune configuration HTTPS ou CORS n'est fournie par cet hôte. L'accès inter-origine par navigateur n'est pas une interface promise.
Requêtes et réponses
Toutes les routes ci-dessous utilisent GET, y compris les commandes qui modifient l'état. Ajoutez chaque route à l'URL de base de son service. Aucun corps de requête ni paramètre de requête n'est déclaré. Les espaces réservés entre accolades sont des segments de chemin obligatoires, sauf si la route décrit explicitement le caractère générique d'arrêt de superposition. N'envoyez pas les accolades littéralement.
Les réponses utilisent la sérialisation JSON WCF et un objet commun :
| Champ JSON | Type | Signification |
|---|---|---|
status | entier | État de l'application selon le tableau ci-dessous. |
message | chaîne ou null | Texte de diagnostic ; ce n'est pas un identifiant stable. |
result | valeur spécifique à la route | Booléen, chaîne, objet, tableau ou null. |
| Valeur | Identifiant | Signification |
|---|---|---|
0 | OK | Aucune erreur d'application signalée. |
1 | COUNTER_NOT_EXIST | Défini dans l'énumération partagée ; non renvoyé explicitement par ces routes. |
2 | TIMER_NOT_EXIST | Défini dans l'énumération partagée ; non renvoyé explicitement par ces routes. |
3 | INTERNAL_ERROR | Le traitement de la requête a échoué. |
4 | PLAYLIST_NOT_FOUND | Aucune playlist disponible ne correspond. |
5 | INVALID_ARGUMENT | Index de séquence invalide, début de playlist vide ou luminosité non entière. |
6 | SEQUENCE_NOT_FOUND | Aucune superposition disponible ne correspond. |
7 | SERVICE_NOT_READY | Contrôle du lecteur indisponible ou en cours d'arrêt, ou contrôles de luminosité indisponibles. |
Les erreurs d'application sont renvoyées dans cette enveloppe sans modifier explicitement le statut HTTP. Une erreur d'application sérialisée normale reste donc une réponse de succès HTTP. Inspectez toujours status, puis le result attendu. Une erreur de transport ou de routage WCF peut avoir un corps différent et ne doit pas être analysée comme une enveloppe garantie. Les tests attendent le code HTTP 404 pour une route inconnue et 405 pour une méthode non prise en charge ; ces attentes n'ont pas été vérifiées par rapport à un hôte en cours d'exécution pour cette référence.
Pour les commandes booléennes, status: 0 et result: true signifient que le chemin de commande a été traité. Ils ne prouvent pas une sortie audiovisuelle réussie ni l'achèvement d'une transition. Certaines méthodes aval interceptent les erreurs ou ne font rien lorsqu'aucun rendu n'existe. Interrogez get_reproduction_state après une commande et attendez l'état souhaité avec un délai d'attente défini par le client. Il n'y a pas d'identifiant de commande, de point de terminaison d'achèvement, de notification push ou de délai de transition spécifié. N'envoyez pas à plusieurs reprises une commande en attendant son effet.
À l'exception de ping, les opérations du lecteur transitent par le répartiteur de la fenêtre de contrôle lorsqu'il est disponible. Cela sérialise leur accès de contrôle sur le thread d'interface utilisateur, mais ne fait pas des requêtes HTTP séparées une transaction atomique. Les opérations statistiques n'utilisent pas cet assistant de répartition du lecteur.
Routes du lecteur
Tous les chemins de ce tableau sont relatifs à /ws/remoteplayer/.
| Route GET | Résultat en cas de succès | Effet ou requête |
|---|---|---|
ping | booléen true | Vérifie que le service répond ; ne vérifie pas la disponibilité du rendu. |
get_instance_name | chaîne | Nom d'instance configuré ; peut être vide. |
list_playlists | tableau de PlaylistInfo | Playlists disponibles dans l'ordre de la collection. |
list_playlist_sequences/{playlist_name} | tableau de SequenceInfo | Séquences dans l'ordre de la playlist ; les indices commencent à zéro. |
list_overlay_sequences | tableau de SequenceInfo | Séquences de superposition toujours au premier plan disponibles. |
get_reproduction_state | ReproductionState | État actuel du contrôle et du rendu. |
start_playlist/{playlist_name} | booléen | Démarre la playlist sélectionnée, y compris les playlists d'action rapide. Les playlists vides sont rejetées. |
start_sequence/{playlist_name}/{sequence_number} | booléen | Démarre la séquence existante sélectionnée. |
start_aot_sequence/{sequence_name_or_file} | booléen | Démarre la superposition sélectionnée (toujours au premier plan) par-dessus l'arrière-plan. |
start_aot_sequence/* | booléen | Gestionnaire d'arrêt par caractère générique. Utilisez start_aot_sequence/ pour supprimer la superposition ; conservez la barre oblique finale. n'envoyez pas d'astérisque littéral. |
stop | booléen | Appelle l'opération d'arrêt du lecteur. Interrogez l'état pour confirmer que la lecture s'est arrêtée. |
pause | booléen | Met en pause si le rendu n'est pas déjà en pause. |
resume | booléen | Reprend la lecture si le rendu est en pause. |
pauseresume | booléen | Bascule l'état de pause du rendu. |
play_next | booléen | Démarre la séquence suivante ; boucle de la dernière à la première. Ne fait rien sans séquence et playlist actives. |
quick_action_exit | booléen | Demande la sortie lorsque le rendu est en mode action rapide ; sinon, ne fait rien. |
set_global_brightness/{brightness_tpc} | booléen | Définit chaque valeur de matrice de luminosité disponible au pourcentage fourni divisé par 100. Aucune requête HTTP de luminosité n'est définie. |
La route de superposition nommée est plus spécifique que le caractère générique. Un nom de superposition inexistant renvoie SEQUENCE_NOT_FOUND ; ce n'est pas une requête d'arrêt. Le routage par caractère générique avec fin vide et d'autres cas particuliers de chemins encodés nécessitent toujours une validation par l'hôte.
Paramètres
| Paramètre | Type et règles |
|---|---|
playlist_name | Chaîne obligatoire. Correspond au nom exact de la playlist ou au nom de base de son fichier de définition, y compris l'extension. La correspondance est sensible à la casse et renvoie la première correspondance dans la collection disponible. Un chemin de définition complet n'est pas une clé de recherche de playlist. |
sequence_number | Entier signé 32 bits obligatoire analysé avec la culture invariante. Doit être compris entre 0 et sequence_count - 1. Les valeurs négatives, non entières, en dépassement de capacité (overflow) et hors limites renvoient INVALID_ARGUMENT après la recherche de la playlist. Une playlist manquante renvoie d'abord PLAYLIST_NOT_FOUND. |
sequence_name_or_file | Chaîne obligatoire pour le démarrage de la superposition. Correspond au nom exact de la superposition, à la valeur du fichier stocké ou au nom de base du fichier. La correspondance est sensible à la casse et renvoie la première correspondance. Préférez les noms ou les noms de base pour les URL. |
brightness_tpc | Texte d'entier signé 32 bits obligatoire. Les valeurs numériques sont limitées entre 0 et 100 pourcent. Les non-entiers et les dépassements de capacité renvoient INVALID_ARGUMENT. L'analyse utilise la culture d'entier par défaut du serveur. Utilisez des chiffres décimaux simples avec un signe optionnel. |
Encodez en pourcentage chaque segment de chemin de chaîne en UTF-8. Par exemple, Demo Show devient Demo%20Show ; encodez un + littéral en %2B, # en %23, ? en %3F et % en %25. n'encodez pas les séparateurs entre les segments de route. Les assistants d'URL utilisent Uri.EscapeDataString pour les références de lancement. Les barres obliques encodées, les barres obliques inverses et les chemins complets du système de fichiers peuvent être affectés par la pile HTTP Windows et ne sont pas vérifiés ici. Préférez un nom unique ou un nom de base sans séparateurs de chemin. Des segments obligatoires manquants peuvent faire échouer le routage WCF avant la validation de l'application.
Données du lecteur
Les noms de champs ci-dessous sont les noms exacts du contrat JSON. L'ordre des propriétés de l'objet n'est pas significatif. Les champs de fichiers contiennent des références stockées et peuvent exposer des informations sur le système de fichiers ; ne présumez pas qu'il s'agit d'URL de téléchargement public.
| Champ PlaylistInfo | Type et signification |
|---|---|
name | chaîne ; nom de la playlist. |
filename | chaîne ; référence du fichier de définition de playlist stocké. |
is_quick_action | booléen ; indicateur d'interruption de playlist. |
has_button | booléen ; indicateur de bouton d'accès rapide. |
button_color | objet ; membres de couleur WCF A, B, G, R (canaux d'octets, 0–255) et ScA, ScB, ScG, ScR (canaux scRGB à virgule flottante). Il ne s'agit pas d'une chaîne CSS. |
sequence_count | entier ; nombre de séquences. |
| Champ SequenceInfo | Type et signification |
|---|---|
name | chaîne ; nom de la séquence. |
filename | chaîne ; référence du fichier de séquence stocké. |
is_on_top | booléen ; true pour les listes de superpositions, false pour les listes de séquences de playlist. |
| Champ ReproductionState | Type et signification |
|---|---|
is_playing | booléen ; une playlist active existe. Ne garantit pas une sortie visible. |
is_paused | booléen ; état de pause du contrôle. |
is_render_active | booléen ; indicateur de rendu actif, false sans rendu. |
is_quickaction | booléen ; une playlist active et un rendu en mode action rapide existent. |
current_playlist | chaîne ; nom de la playlist active, sinon vide. |
current_playlist_file | chaîne ; référence de définition de la playlist active, sinon vide. |
current_sequence | chaîne ; nom de la séquence active, sinon vide. |
current_sequence_index | entier ; index de la séquence active (commençant à zéro), sinon -1. |
current_overlay_sequence_name | chaîne ; nom de la superposition active, sinon vide. |
current_overlay_sequence_file | chaîne ; référence du fichier de superposition actif, sinon vide. |
current_sequence_elapsed_time | chaîne ; compteur de séquence écoulé multiplié par 1000, en millisecondes. |
current_sequence_total_time | chaîne ; durée de la séquence en millisecondes, tronquée vers zéro. |
Les valeurs de temps sont des chaînes JSON, et non des nombres ou des intervalles de temps formatés. Les deux champs de temps valent "0" en l'absence de séquence active. Leur interpolation utilise la culture du serveur ; ne présumez pas d'un séparateur décimal invariant ou d'une précision de mesure à la milliseconde. Les valeurs de fichier/nom copiées à partir du modèle peuvent être nulles. Une erreur d'application peut renvoyer des résultats nuls, vides ou partiellement renseignés ; vérifiez status avant de les utiliser.
Routes et données onTV
Tous les chemins de ce tableau sont relatifs à /ws/statsmeter/. Conservez l'orthographe mesures exactement telle qu'elle est affichée.
| Route GET | Résultat en cas de succès | Effet ou requête |
|---|---|---|
start_on_tv_interval | OnTVInterval | Ouvre un intervalle de mesure ; un intervalle déjà ouvert est conservé. |
stop_on_tv_interval | OnTVInterval | Ferme le dernier intervalle s'il est ouvert. |
state_on_tv_interval | OnTVInterval | Renvoie le dernier intervalle, y compris un intervalle fermé. |
get_all_intervals_on_tv | tableau de OnTVInterval | Renvoie la liste des intervalles du compteur de rendu. Aucune pagination ni filtre de date n'est déclaré. |
get_mesures_statistics | TransmissionStatistics | Compte et totalise les intervalles terminés. |
Ces commandes marquent des périodes de mesure. Elles ne démarrent ni n'arrêtent la lecture de la playlist et ne détectent pas de signal de diffusion. Le contrôleur renvoie un intervalle par défaut, ou une liste vide pour l'opération de liste, lorsqu'aucun rendu n'existe. Un rendu sans compteur de statistiques peut renvoyer null ; le démarrage et l'arrêt rencontrent alors la déréférenciation de journalisation du service et signalent une erreur interne. Il peut s'agir d'une réponse OK sans mesure réelle.
| Champ OnTVInterval | Type et signification |
|---|---|
begin | Chaîne DateTime JSON WCF ; début de l'intervalle. |
end | Chaîne DateTime JSON WCF ; fin de l'intervalle. |
Le marqueur non défini est une date dont l'année est 1970, initialisée au 1er janvier 1970. Un intervalle ouvert a une fin non définie. Aucun intervalle enregistré ne produit d'objet par défaut avec les deux dates non définies. Des arrêts répétés laissent un intervalle fermé inchangé. Les dates proviennent de DateTime.Now sur le serveur. WCF utilise la représentation /Date(milliseconds[+or-offset])/, avec un échappement possible des barres obliques JSON ; ce n'est pas un contrat ISO 8601. Le décalage optionnel et la gestion des DateTime locaux/non spécifiés doivent être vérifiés sur l'hôte déployé. N'interprétez pas la sentinelle comme un véritable horodatage mesuré.
| Champ TransmissionStatistics | Type et signification |
|---|---|
intervals_recorded | entier ; nombre où les années de début et de fin diffèrent de 1970. |
total_seconds_in_tv | secondes entières ; somme des millisecondes des intervalles terminés, convertie en entier 32 bits, puis divisée par 1000 et arrondie avec Math.Round. Les intervalles ouverts sont exclus. |
L'accumulation de millisecondes utilise une conversion en entier 32 bits avant arrondi. De longs historiques peuvent dépasser cette plage. Ne traitez pas cela comme un compteur de durée à précision illimitée ou comme un historique de durée de vie garanti entre les redémarrages. Les captures d'erreurs statistiques signalent INTERNAL_ERROR ; leur message peut rester null.
Exemples
Toutes les requêtes et valeurs JSON de cette section sont illustratives. L'hôte, les noms et les références de fichiers sont des espaces réservés ne contenant aucune donnée privée. Les réponses sont des enveloppes complètes, sauf indication contraire. L'ordre des propriétés et les espaces JSON peuvent différer.
Vérifiez la disponibilité depuis l'ordinateur du lecteur lorsque le port configuré est 8083 :
curl "http://127.0.0.1:8083/ws/remoteplayer/ping"
{"message":null,"result":true,"status":0}
Répertoriez les séquences dans une playlist disponible nommée 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}
Démarrez sa première séquence, puis interrogez l'état. Il s'agit de deux requêtes distinctes :
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"
Réponse de commande illustrative :
{"message":null,"result":true,"status":0}
Réponse d'état illustrative après la transition :
{"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 index de séquence invalide dans une playlist existante :
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}
Une requête de playlist manquante :
{"message":"Playlist [Missing] not found.","result":[],"status":4}
Démarrez une superposition nommée Demo Overlay, puis supprimez-la :
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/"
Définissez la luminosité globale à 50 pourcent :
curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"
Ouvrez, inspectez et fermez un intervalle onTV, puis lisez les totaux :
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"
Réponse statistique illustrative après un intervalle de cinq secondes terminé :
{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}
Limitations
Les décalages de date, le routage par caractères génériques, les corps d'erreur HTTP et l'accès spécifique au déploiement nécessitent une validation sur l'installation cible.
Aucune limite de débit, isolation des clients, transaction de requête, garantie d'idempotence générale ou garantie d'achèvement audiovisuel n'est implémentée par cette couche d'API. Les commandes utilisent GET, de sorte que l'aperçu des liens, le préchargement, la mise en cache et les nouvelles tentatives automatiques peuvent être dangereux pour les commandes. Utilisez un client qui envoie des requêtes uniquement en cas de besoin et ne réutilise pas les réponses de requêtes mises en cache. Le code du serveur n'établit pas de contrat de contrôle du cache.
L'interface HTML onTV, les métadonnées WCF et les points de terminaison mex sont distincts des opérations JSON documentées ici. Ce ne sont pas des routes de commande de lecteur supplémentaires. Aucune opération de téléchargement (upload/download), d'édition de playlist, de lecture de la luminosité ou d'abonnement à des événements n'est déclarée dans ces deux contrats JSON.