API

L'API OPENSONG

Une interface d’automatisation pour OpenSong permettant d’accéder aux fonctionnalités principales en utilisant une approche REST sur HTTP et WebSocket. Cette API est disponible depuis OpenSong 2.0 beta2.

BACKGROUND

OpenSong est une application pour gérer et projeter des chansons, des paroles et des accords, des extrait de la Bible, du texte libre, des images et des vidéos. OpenSong est multiplateforme, mais le support est limité aux plates-formes mises à disposition par l’IDE, qui couvre actuellement MacOS, Windows et Linux. Il y a un nombre croissant de demandes pour rendre OpenSong disponible sur d’autres plates-formes, telles que iOS, Android ou les plates-formes mobiles en général. Cela nécessite une réécriture complète dans un autre langage spécifique à la plate-forme, ou une approche différente : une API. Cette API facilite également l’automatisation ou le contrôle à distance par exemple à partir d’un logiciel de contrôle de spectacle.

OBJECTIF

L’API OpenSong permet d’accéder aux éléments de base d’OpenSong pour la récupération d’informations ou la modification du statut. Cela signifie que des applications externes peuvent demander par exemple des informations d’état, ou contrôler une présentation sans nécessiter un portage de la logique métier d’OpenSong sur une plate-forme différente.

Un exemple de méthode exposée par l’API OpenSong consiste à récupérer l’état actuel sous forme XML :

				
					GET http://localhost:8082/presentation/status

La réponse est généralement un document XML de la forme suivante, par exemple en réponse à la requête ci-dessus :

				
					 <?xml version="1.0" encoding="UTF-8"?>
    <response resource="presentation" action="status">
      <presentation running="1">
        <screen mode="N">normal</screen>
        <slide itemnumber="1">
          <name>Testslide</name>
          <title>Untitled</title>
         </slide>
       </presentation>
    </response>

La valeur de l’attribut de présentation en cours d’exécution est 1 ou 0 selon qu’une présentation est en cours d’exécution ou non.

Les nœuds enfants de présentation ne sont disponibles qu’en cas de présentation active (attribut running = 1).

L’itemnumber de l’attribut de diapositive est un identifiant unique (numérique) d’une diapositive dans un ensemble. Ce numéro est généré au lancement d’une présentation et ne changera pas au cours d’une présentation. Les diapositives insérées dynamiquement auront également un numéro unique. Le numéro d’article n’est donc pas toujours un numéro de séquence indiquant la position de la lame dans le jeu.

SPECIFICATION

Toutes les communications passent par HTTP, OpenSong lui-même est le serveur, fonctionnant par défaut sur le port 8082. L’API est un service RESTful. Les commandes sont exécutées à l’aide des méthodes GET et POST :

Les requêtes GET sont utilisées pour l’état ou la récupération de données
Les requêtes POST sont utilisées pour toutes les commandes susceptibles de changer de statut

Les réponses consistent généralement en un document XML, à l’exception d’actions spécifiques, par exemple la récupération de l’image de la diapositive en cours, qui renverra une image JPEG.

Une requête HTTP a la forme typique suivante :

http://host:port/resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

host : identifie la machine exécutant OpenSong, par exemple localhost
port : spécifie le port sur lequel OpenSong écoute les requêtes, par défaut 8080
resource : partie obligatoire de la demande pour sélectionner une ressource qui gérera les actions, le cas échéant
action : une chaîne facultative spécifiant l’action à exécuter
identifier : une valeur facultative pour sélectionner un élément spécifique. La signification et le type autorisé dépendent de la ressource et de l’action
param1…paramN : un nom de paramètre facultatif. Si les paramètres s’appliquent est spécifique à l’action. L’ordre des paramètres n’est pas pertinent.
value1…valueN : une valeur de paramètre facultative pour param. Les valeurs de paramètre valides sont spécifiques à l’action

AUTHENTIFICATION

Un niveau d’authentification de base est utilisé. Généralement, l’authentification est requise pour toutes les requêtes POST. La plupart des requêtes GET ne nécessitent pas d’authentification. Dans le cas où l’authentification est requise, mais qu’aucune information d’identification n’est fournie, OpenSong répondra avec une réponse de demande d’authentification de base HTTP. OpenSong ne facilite pas la configuration de plusieurs utilisateurs et mots de passe. L’authentification est gérée par une clé d’authentification unique qui doit être fournie dans l’en-tête de la demande d’authentification de base :

				
					Authorization: Basic __base64_encoded_key__

RESSOURCES

Les sections suivantes décrivent les ressources disponibles. Notez que plusieurs URI sont répartis sur plusieurs lignes en raison du retour à la ligne automatique. Tous les URI doivent être saisis sur une seule ligne, sans saut de ligne, à l’exception de ceux explicitement séparés par ‘ou’ sur des lignes séparées.

PRESENTATION

Gestion des informations dans une présentation en cours d’exécution.

Cette ressource nécessite qu’une action soit spécifiée.

Méthode	URI	Implémenté	Response or consequence
GET	/presentation/status	oui	Le statut d’OpenSong, voir l’exemple de réponse ci-dessus.
GET	/presentation/slide or /presentation/slide/list	oui	Une liste des diapositives de la présentation actuelle, y compris les génériques des diapositives (nom, titre, numéro de la diapositive).
GET	/presentation/slide/identifier	oui	Les données XML brutes d’une diapositive. L’identifiant est le numéro d’élément de la diapositive tel qu’il est disponible dans le XML fourni par la liste d’actions.
GET	/presentation/slide/identifier/preview[/width:x][/height:y][/quality:value]	oui	Aperçu de l’image pour la diapositive au format de fichier JPEG. Les dimensions de l’aperçu correspondent par défaut à la taille de l’aperçu sur la fenêtre de l’assistant de présentation ou 160×120 si l’assistant de présentation n’est pas actif. Spécifiez éventuellement le paramètre width pour définir la largeur en pixels (max 4096) en combinaison ou non avec le paramètre height pour définir la hauteur en pixels (max 4096). La qualité du paramètre peut éventuellement être définie pour spécifier la qualité de l’aperçu JPEG, 0=qualité la plus faible, 100=qualité la plus élevée. L’identifiant est le numéro d’élément de la diapositive tel qu’il est disponible dans le XML fourni par la liste d’actions, ou « actuel ».
GET	/presentation/slide/identifier/image[/width:x][/height:y][/quality:value]	oui	Image de la diapositive au format de fichier JPEG. Les dimensions de l’image correspondent par défaut à la taille de la fenêtre actuelle, qui est égale aux dimensions de l’écran du projecteur. Spécifiez éventuellement le paramètre width pour définir la largeur en pixels (max 4096) en combinaison ou non avec le paramètre height pour définir la hauteur en pixels (max 4096). Les paramètres width et height n’ont pas d’influence lors de l’utilisation de l’identifiant ‘current’ pour récupérer la diapositive en cours de présentation. La qualité du paramètre peut éventuellement être définie pour spécifier la qualité de l’aperçu JPEG, 0=qualité la plus faible, 100=qualité la plus élevée. L’identifiant est le numéro d’élément de la diapositive tel qu’il est disponible dans le XML fourni par la liste d’actions, ou « actuel ».
POST	/presentation/slide/song[/folder:name]/song:name[/after:slide_number][/order:presentationorder]	oui (as of release 2.2, rev. 917)	Insère une chanson dans l’ensemble de diffusion actuel. La valeur du dossier de paramètre est le nom du dossier à partir duquel charger les chansons. En cas d’absence, la chanson se trouve dans la racine du dossier de chansons. Le paramètre song est le nom du morceau à charger. Le paramètre après est la position du numéro de diapositive après laquelle le morceau doit être inséré. A 0, le morceau sera inséré comme premier élément du set. En cas d’absence, la chanson sera insérée après la diapositive (groupe) en cours. L’ordre des paramètres spécifie les couplets facultatifs, le refrain, le pont, les éléments .. d’une chanson qui doivent être ajoutés (c’est ce que l’on appelle dans l’application «l’ordre de présentation»). En cas d’absence, l’ordre de présentation par défaut de la chanson sera utilisé. Il est permis de spécifier plusieurs versets en utilisant une liste séparée par des virgules, par ex. ‘V1,C,V2,B,V2,V3’
POST	/presentation/slide/scripture/[tbd]		Insérer une nouvelle écriture (nécessite des paramètres supplémentaires, à définir)
POST	/presentation/slide/identifier	oui	Passez directement à une diapositive. L’identifiant est le numéro d’élément de la diapositive tel qu’il est disponible dans le XML fourni par la liste d’actions.
POST	/presentation/slide/next	oui	Passer à la diapositive suivante
POST	/presentation/slide/previous	oui	Passer à la diapositive précédente
POST	/presentation/slide/first	oui	Passer à la première diapositive
POST	/presentation/slide/last	oui	Passer à la dernière diapositive
POST	/presentation/section/next	oui	Aller à la section suivante
POST	/presentation/section/previous	oui	Aller à la section précédente
POST	/presentation/song/identifier	oui	Sauter à une chanson spécifique dans l’ensemble. L’identifiant est le numéro d’ordre du morceau.
POST	/presentation/song/current/chorus	oui	Aller au (premier suivant) refrain dans la chanson en cours (le cas échéant dans la chanson en cours).
POST	/presentation/song/current/bridge	oui	Passer au pont (premier suivant) dans le morceau en cours (le cas échéant dans le morceau en cours).
POST	/presentation/song/current/prechorus	oui	Aller au (premier suivant) pré-refrain dans la chanson en cours (le cas échéant dans la chanson en cours).
POST	/presentation/song/current/tag	oui	Aller à la balise (première suivante) dans la chanson en cours (le cas échéant dans la chanson en cours).
POST	/presentation/song/current/verse/verse:number	oui	Passer à un couplet spécifique dans la chanson en cours (le cas échéant dans la chanson en cours).
POST	/presentation/screen/normal	oui	Passer (retour) au mode d’affichage normal de l’écran.
POST	/presentation/screen/[toggle_]black	oui	Afficher l’écran noir. Si l’écran actuel est un écran noir, passez à l’écran normal.
POST	/presentation/screen/[toggle_]white	oui	Afficher l’écran blanc. Si l’écran actuel est un écran blanc, passez à l’écran normal.
POST	/presentation/screen/[toggle_]hide	oui	Afficher l’arrière-plan actuel (masquer le texte). Si le mode d’écran actuel est masqué, passez à l’écran normal.
POST	/presentation/screen/[toggle_]logo	oui	Afficher le logo sur l’écran actuel. Si le logo s’affiche, passez à l’écran normal.
POST	/presentation/screen/[toggle_]freeze	oui	Geler l’écran actuel, ne pas mettre à jour les changements d’écran. Si le mode d’écran actuel est l’écran gelé, passez à l’écran normal.
POST	/presentation/screen/alert/message:text	oui	Affiche une alerte à l’écran. Message de paramètre, valeur textuelle est le message texte à afficher. Lorsque le paramètre est absent ou vide, l’alerte actuellement affichée (le cas échéant) sera supprimée. Vous pouvez utiliser du texte brut (ascii), ou – à partir de la version 2.2, rév. 918 – UTF-8.
POST	/presentation/close	oui	Terminer la présentation en cours (sans confirmation interactive de l’utilisateur).

CHANT

Échange de données relatives à la chanson.

Méthode	URI	Implémenté	Réponse ou consequence
GET	/song or /song/list[/folder:name]	oui	Une liste de toutes les chansons dans le répertoire racine des chansons, ou la chanson dans le dossier spécifié par le paramètre ‘folder’.
GET	/song/[detail]/identifier[/folder:name]	oui	Le XML brut d’une chanson.
GET	/song/folders	oui	Une liste avec les noms des dossiers de morceaux disponibles.
POST	/song/load/identifier[/folder:name]	oui (2.0 final)	Charge le morceau spécifié par le nom du morceau comme identifiant.
POST	/song/present/identifier[/folder:name][/slide:index][/display:mode]	oui (2.0 final)	Démarre une présentation en utilisant la chanson spécifiée par le nom de l’ensemble comme identifiant. En option, une diapositive de départ peut être spécifiée. L’omission du paramètre a le même effet que l’utilisation de slide_index=1. Le paramètre d’affichage facultatif détermine le mode d’affichage où 1 est un affichage simple et 2 est un affichage double (lancement de l’assistant de présentation). Le double affichage est par défaut. La diapositive de paramètres et l’affichage des paramètres peuvent être permutés et les deux sont facultatifs.

SET

Échange de données liées au set.

Méthode	URI	Implémenté	Réponse ou consequence
GET	/set or /set/list	oui	Une liste avec les noms de tous les ensembles disponibles.
GET	/set/slide/identifier	oui	Une liste de diapositives dans l’ensemble spécifié par le nom de l’ensemble comme identifiant. Un court résumé par diapositive sera renvoyé. Pour plus de détails sur la diapositive, spécifiez une diapositive par index, voir ci-dessous.
GET	/set/slide/identifier/slide:index	oui	Le contenu complet (brut) de la diapositive de l’ensemble spécifié par le nom de l’ensemble comme identifiant et l’index de la diapositive comme paramètre.
POST	/set/load/identifier	oui (2.0 final)	Charge l’ensemble spécifié par le nom d’ensemble comme identifiant.
POST	/set/present/identifier[/slide:index][/display:mode]	oui (2.0 final)	Démarre une présentation en utilisant l’ensemble spécifié par le nom d’ensemble comme identificateur. En option, une diapositive de départ peut être spécifiée. L’omission du paramètre a le même effet que l’utilisation de slide_index=1. Le paramètre d’affichage facultatif détermine le mode d’affichage où 1 est un affichage simple et 2 est un affichage double (lancement de l’assistant de présentation). Le double affichage est par défaut. La diapositive de paramètres et l’affichage des paramètres peuvent être permutés et les deux sont facultatifs.

WS

Cette ressource permet d’accéder à l’interface websocket. L’utilisation de websockets permet une communication bidirectionnelle et une transmission d’état d’OpenSong au client au lieu d’interroger à l’aide des actions répertoriées ci-dessus.

Pour lancer une session WebSocket, connectez le client à

				
					ws://host:port/ws

L’interface socket fournit un accès interactif complet à toutes les ressources en envoyant la requête URI régulière sous forme de données texte à OpenSong :

				
					resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

L’implémentation de WebSocket est basique et limitée à l’envoi de trames de données complètes pour du texte ou des données binaires à l’aide de la spécification WebSocket approuvée RFC 6455. À l’heure actuelle, la fonctionnalité implémentée est entièrement rétrocompatible avec le projet hybi-10. Les websockets sécurisés (wss) ne sont pas pris en charge.

La connexion websocket n’est pas authentifiée, par conséquent, les actions qui modifient l’état d’OpenSong, telles que le chargement d’un ensemble ou la modification d’une diapositive ne sont pas autorisées. Cela signifie que la ressource ws autorise toutes les actions GET, plus les actions de la ressource ws :

URI	Implémenté	Activité
/ws/subscribe/identifier	oui	Active les notifications pour un sujet spécifique, généralement identique à un nom de ressource. Pris en charge : présentation
/ws/unsubscribe/identifier	oui	Désactive les notifications pour un sujet spécifique, généralement identique à un nom de ressource.