Change history
Version 0.1 20-05-2022    
                            Initial version

Version 0.2 23-05-2022 
                            Added missing error code 0
                            Added authentification section
                            Added uptimeMs field in getLiveInfo result

Version PDF à télécharger en bas de l'article.

TABLE DES MATIÈRES

• Etude de cas
• Synoptique de fonctionnement du Live
  • Le principe général est le suivant :
  • Les limitations
• Syntaxe des commandes
  • Explications
  • Authentification
• Liste des commandes
  • 1. Commande startLive
  • 2. Commande stopLive
  • 3. Commande pugeLive
  • 4. Commande getLiveInfo
• Codes d’erreurs

Etude de cas : 

• Comment piloter le live Okast Channels sans passer par son interface ?
• Comment intégrer le pilotage du live depuis un outils tiers ?

Le principe général est le suivant :

• Le moteur de gestion de live fournit une décorrélation entre l’acquisition du signal Live (=la récupération du signal Live entrant) et la restitution du Live au sein du signal produit par le playout.

• L’acquisition du signal Live entrant s’effectue automatiquement : lorsque le client pousse un signal RTMP vers le serveur, l’acquisition démarre automatiquement. Elle cesse dès que le client déconnecte le flux.

• La restitution est une mécanique en deux temps : 
  • La portion de Live à restituer est comprise entre deux instants : la prise d’antenne et la fin d’antenne.
    
    
  • D’autre part, le playout prévoit une tuile de live, dédiée à la restitution de cette portion de live. Cependant, la portion de Live à restituer et la tuile de live ne sont généralement pas synchronisées (car le playout suit une programmation stricte, et doit terminer l’élément de playlist en cours de programmation avant de démarrer le live).
    
    
  • Ainsi, il y a un découplage entre la demande de restitution d’un Live, et sa restitution effective :
    
    
  • La demande de restitution s’effectue par un appel à l’API, synchronisé sur la prise d’antenne. Le serveur commence alors la mise en tampon du signal Live. Cela signifie que lorsque le Live sera restitué, la restitution commencera précisément en ce point (même si la restitution a lieu une heure plus tard).
    
    
  • La restitution effective commence dès lors que le playout commence la lecture de la tuile de live. Il commence alors la restitution à partir du début de son tampon d’acquisition.
    
    
  • La demande d’arrêt de restitution (commande d’API) permet de stopper le remplissage du tampon de restitution. Cela signifie que la restitution du signal Live s’arrêtera en ce point précis.
     
  • Le playout épuise son tampon d’acquisition. Ensuite il peut enchaîner sur l’élément suivant de sa playlist.

Les limitations :

Le tampon de restitution peut être plus court / long que la tuile de live prévue dans le playout. 

Le playout dispose d’un paramètre de tolérance (N secondes), qui crée alors une zone de tolérance au niveau de la tuile de Live.

• Si le tampon est épuisé hors de la zone de tolérance (ex : la tuile de live fait 1h, la tolérance est de 5min, le tampon est épuisé au bout de 10min), alors le playout reste sur la tuile de Live, et affiche la mire. Ceci permet d’éviter une fin prématurée du live alors qu’une erreur technique est survenue sur le flux, mais qu’il peut reprendre dans la foulée.
  
  
• Si le tampon est épuisé dans la zone de tolérance (ex : la tuile de live fait 1h, la tolérance est de 5min, et le tampon est épuisé au bout de 58min), alors le playout considère que le live est prématurément terminé, il enchaîne naturellement sur l’élément suivant.
  
  
• Si le tampon n’est pas épuisé alors que la durée de la tuile de live est épuisée :
  • Le playout va continuer la restitution dans la zone de tolérance (dépassement de N minutes autorisé).
    
    
  • Au delà, le playout coupe la restitution et enchaîne sur l’élément de playlist suivant.

https://<URL_SERVER>/synthesia-live-api/?command=<COMMAND>

Explications :

• URL_SERVER : l’adresse du serveur
• COMMAND : la commande à appliquer

L’appel retourne systématiquement un fichier JSON en réponse aux appels. La structure du fichier JSON est la suivante :

{
"error": <true|false>,
"errorCode": <API_ERROR_CODE>,
"message": "<API_ERROR_MESSAGE>",
"info": "<API_RESULT_MORE_INFO>"
}

où

• Error : indique si une erreur est survenue lors de l’appel ou du traitement de la commande.
  
  
• ErrorCode : donne le code d’erreur (0 si pas d’erreur).
  
  
• Message : le message associé au code d’erreur.
  
  
• Info : informations complémentaires (en cas d’erreur, ou de demande d’informations sur le statut du Live).

https://<URL_SERVER>/synthesia-live-api/?command=startLive

{
    "error": false,
    "errorCode": 0,
    "message": "API call successfully processed",
    "info": {
        "lives": [
            {
                "id": "d21abb96-c707-9b9d-f074-81167a8bea3b",
                "name": "Le Figaro Live",
                "schedule": false,
                "scheduleStart": "0:0:0",
                "scheduleEnd": "0:0:0",
                "scheduleDays": "0:0:0:0:0:0:0"
            }
        ]
    }
}

https://<URL_SERVER>/synthesia-live-api/?command=stopLive

Format de la réponse

{
    "error": false,
    "errorCode": 0,
    "message": "API call successfully processed",
    "info": {
        "lives": [
            {
                "id": "d21abb96-c707-9b9d-f074-81167a8bea3b",
                "name": "Le Figaro Live",
                "schedule": false,
                "scheduleStart": "0:0:0",
                "scheduleEnd": "0:0:0",
                "scheduleDays": "0:0:0:0:0:0:0"
            }
        ]
    }
}

La balise info contient des informations techniques générales sur l’objet live au sein du playout (qui ne sont pas nécessairement utiles ici).

3. Commande pugeLive

https://<URL_SERVER>/synthesia-live-api/?command=purgeLive

Format de la réponse

{
    "error": false,
    "errorCode": 0,
    "message": "API call successfully processed",
    "info": {
        "lives": [
            {
                "id": "d21abb96-c707-9b9d-f074-81167a8bea3b",
                "name": "Le Figaro Live",
                "schedule": false,
                "scheduleStart": "0:0:0",
                "scheduleEnd": "0:0:0",
                "scheduleDays": "0:0:0:0:0:0:0"
            }
        ]
    }
}

La balise info contient des informations techniques générales sur l’objet live au sein du playout (qui ne sont pas nécessairement utiles ici).

4. Commande getLiveInfo

URL de requête

https://<URL_SERVER>/synthesia-live-api/?command=getLiveInfo

Format de la réponse

{
    "error": false,
    "errorCode": 0,
    "message": "API call successfully processed",
    "info": {
        "live_server": {
            "running": true,
            "uptime": "01:49:30.668",
            "uptimeMs": 6570668
        },
            "live_source": {
            "running": true,
            "uptime": "00:07:18.080",
            "uptimeMs": 438080,
            "bitrate": 5608343
        },
            "live_restitution": {
            "running": true,
            "uptime": "00:02:32.240",
            "uptimeMs": 6570668
        }
    }
}

La balise info contient des informations sur le statut de traitement du Live :

• Live_server : statut du serveur RTMP d’ingest :
  • Running : indique si le serveur RTMP est up (devrait être toujours à true).
  • Uptime : indique depuis combien de temps le serveur RTMP est up.
• Live_source : statut d’ingest de la source Live :
  • Running : indique si la source Live est actuellement en cours de réception.
  • Uptime : indique depuis combien de temps la source Live est connectée.
     
• Live_restitution : statut de restitution de la source Live :
  • Running : indique si la source Live est actuellement en demande de restitution. La restitution devient active dès lors qu’une commande de démarrage (startLive) a été passée, mais cela ne signifie pas que le live est actuellement on-air (car cela dépend de la position de la tuile de live au sein de la programmation).
  • Uptime : indique depuis combien de temps la source Live est en demande de restitution.

Codes d’erreurs 

0 : API call successfully processed
 → Pas d’erreur, l’appel s’est effectué correctement.

100 : No command specified
→ Aucune commande n’a été spécifiée (paramètre command manquant).

101 : Unknown command specified
 → La commande n’est pas reconnue.

300: Error while calling WS URL
 → Une erreur est survenue lors de l’application de la commande.