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
Download PDF version at the bottom of the article.
TABLE DES MATIÈRES
Case study:
- How to control Okast Channels live without using its interface?
- How to integrate live control from a third-party tool?
Live operation diagram
The following diagram summarizes how Live works:
The general principle is as follows:
- The live management engine provides decorrelation between Live signal acquisition (=retrieval of the incoming Live signal) and Live restitution within the signal produced by the playout.
- Live signal acquisition is automatic: when the client pushes an RTMP signal to the server, acquisition starts automatically. It stops as soon as the client disconnects the stream.
- Playback is a two-stage process:
- On the one hand, the portion of Live to be played back falls between two points in time: the start of the broadcast and the end of the broadcast.
- On the other hand, the playout includes a live tile, dedicated to the playback of this portion of Live. However, the portion of Live to be played back and the live tile are generally not synchronized (because the playout follows a strict schedule, and must finish the playlist item being programmed before starting the live).
- As a result, there is a decoupling between the request to play a Live and its actual playback:
- The playback request is made by a call to the API, synchronised with the antenna feed. The server then starts buffering the Live signal. This means that when the Live signal is played back, playback will start precisely at that point (even if playback takes place an hour later).
- Actual playback begins as soon as the playout starts playing the Live tile. It then starts playback from the beginning of its acquisition buffer.
- The stop playback request (PLC command) stops the playback buffer from filling up. This means that playback of the Live signal will stop at this precise point.
- The playout exhausts its acquisition buffer. It can then move on to the next item in its playlist.
Limitations:
The restitution buffer can be shorter/longer than the live tile provided in the playout. The playout has a tolerance parameter (N seconds), which creates a tolerance zone for the Live tile.
- If the buffer is used up outside the tolerance zone (e.g. the live tile is 1 hour long, the tolerance is 5 minutes, the buffer is used up after 10 minutes), the playout stays on the live tile and displays the test pattern. This prevents the live event from ending prematurely when a technical error has occurred in the stream, but it can resume immediately.
- If the buffer is exhausted within the tolerance zone (e.g. the live tile is 1 hour long, the tolerance is 5 minutes, and the buffer is exhausted after 58 minutes), then the playout considers the live to have ended prematurely and naturally moves on to the next element.
- If the buffer has not run out and the live tile has run out of time:
- The playout will continue the playback within the tolerance zone (exceeding N minutes authorised).
- If the buffer is exceeded, the playout will stop and move on to the next playlist item.
Command syntax
The general syntax for calling the API is as follows:
https://<URL_SERVER>/synthesia-live-api/?command=<COMMAND>
Explanations:
- URL_SERVER: the server address
- COMMAND : the command to apply
The call systematically returns a JSON file in response to the calls. The structure of the JSON file is as follows:
{
"error": <true|false>,
"errorCode": <API_ERROR_CODE>,
"message": "<API_ERROR_MESSAGE>",
"info": "<API_RESULT_MORE_INFO>"
}where
- Error: indicates whether an error has occurred when calling or processing the command.
- ErrorCode: gives the error code (0 if no error).
- Message: the message associated with the error code.
- Info: additional information (in the event of an error, or a request for information on the status of Live).
Authentication
a. Access to the API is via HTTPs basic-auth authentication (login / password).
b. Credentials are provided by Vizion'R at the same time as the API server URL.
List of commands
1. StartLive command
Command effect : Starts buffering the live signal for playback. This command triggers the buffering of the Live signal. When the playout starts playback of the Live signal, it will start playback at this point.
Request URL
https://<URL_SERVER>/synthesia-live-api/?command=startLive
Response format
{
"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"
}
]
}
}The info tag contains general technical information about the live object within the playout (which is not necessarily useful here).
2. stopLive command
Effect of the command
Stops buffering the live signal for playback. The command stops buffering the live signal. The playout will stop playing the live signal at this point.
Request URL
https://<URL_SERVER>/synthesia-live-api/?command=stopLive
Response format
{
"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"
}
]
}
}The info tag contains general technical information about the live object within the playout (which is not necessarily useful here).
3. pugeLive command
Command effect
Clears the current acquisition buffer. The command clears the current restore buffer. This command can be useful before starting a new Live restore request, to ensure that the current buffer is empty. If the command is executed while the Live is being played back, clearing the buffer generally causes a short return to the test pattern (because the playout no longer has any Live data to play, so the test pattern is played back until the buffer fills sufficiently to resume playing back the Live).
Request URL
https://<URL_SERVER>/synthesia-live-api/?command=purgeLive
Response format
{
"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"
}
]
}
}4. getLiveInfo command
Command effect
Retrieves technical information about Live.
Request URL
https://<URL_SERVER>/synthesia-live-api/?command=getLiveInfo
Response format
{
"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
}
}
}The info tag contains information about the processing status of the Live :
- Live_server: status of the ingest RTMP server:
- Running: indicates whether the RTMP server is up (should always be true).
- Uptime: indicates how long the RTMP server has been up.
- Live_source: ingest status of the Live source:
- Running: indicates whether the Live source is currently being received.
- Uptime: indicates how long the Live source has been connected.
- Live_restitution: restitution status of the Live source:
- Running: indicates whether the Live source is currently requesting restitution. Restitution becomes active as soon as a start command (startLive) has been issued, but this does not mean that the Live is currently on-air (as this depends on the position of the Live tile within the schedule).
- Uptime: indicates how long the Live source has been requesting playback.
Error codes
0: API call successfully processed
→ No error, the call was processed correctly.
100: No command specified
→ No command was specified (command parameter missing).
101: Unknown command specified
→ The command is not recognised.
300: Error while calling WS URL
→ An error occurred while applying the command.