← Back to Articles

Currently Xeoma supports WebRTC for streaming any video into browsers, allowing for a more consistent experience for viewers and a lower overall load on the server. Additionally, this opens up new integration options, so that the WebRTC video from Xeoma can be used on a website or in a third-party application. In this article we’ll look into the ways such integration can be implemented, specifically, into Xeoma’s new WebRTC API. Note that the structure of requests and responses is largely similar to the JSON API. All commands listed below are GET-requests. Xeoma server requires a stable connection to a STUN server for the WebRTC API’s proper functioning.
The API in question is divided into two major parts: online view and archive view.
All commands begin with http://IP:10090/ – where IP is the server’s IP-address. The end of each request is listed and described below.

Online view

1. ?get_available_webrtc_streams=
   This request asks for the current list of cameras on the server and their parameters that we’ll require to get the video. The response looks like this:
   {
"192.168.0.77 Cam_2": "?sourcewebrtc=687474703A2F2F6C6F63616C686F73743A31303039302F766964656F322E6D6A70673F757365723D&webServerId=WebconnectorTransmitter.2"
}
   The vital parts of this response are the parameters sourcewebrtc and webServerId, the IP and camera name are there just to identify a specific camera.
2. ?sourcewebrtc=687474703A2F2F6C6F63616C686F73743A31303039302F766964656F322E6D6A70673F757365723D&webServerId=WebconnectorTransmitter.2&example=
   This request asks for a WebRTC stream from a given camera (the value for sourcewebrtc) with a given Web Server module (the value for webServerId) in its chain. In a browser, the response will be an online video from the camera on an otherwise blank page.
3. Before an external site or app can access a stream, they need to make an initial interaction with the WebRTC API, this job falls on the JS script webrtc_view_common.js (you will find it available in XeomaWeb folder, part of the main directory). This script contains the method connectWithWebrtcServer – it needs to be called when the page is loaded. This same script will handle all the rest of the work to fetch the video.
4. The page will need one more JS script to be loaded – webrtc_adapter_min.js, located in the same directory as the previous one.
5. The resulting stream needs to be written with the <video> tag. Another method from webrtc_view_common.js (specifically, onRemoteTrack) will attach the stream to this tag. Thus, the HTML-file should have these lines:
   <video id="remote-video" autoplay></video>
<audio id="remote-audio" autoplay></audio>

Archive view

1. ?archive_list=
   This request asks for the names of all available archives on the server. The response looks like this:
   Preview+Archive.12
Preview+Archive.18
Preview+Archive.7
Preview+Archive.21
Preview+Archive.24
2. ?archive_date_list=&archive=NameArchive
   NameArchive – the given archive’s name.
   This request asks for all the dates (days) that currently have any recordings within that archive. Note that Preview+Archive.12 will turn into Preview%2BArchive.12. The response looks like this (dates are in the format yyyy-mm-dd):
   2020-08-22
2020-08-23
2020-08-24
2020-08-25
2020-08-31
3. ?archive_minutes=&archive_date=2020-08-24&archive=NameArchive
   2020-08-24 – the date you need.
   This request asks for the list of all the minutes that had any recordings within that day. The time zone here is taken from the server. The response looks like this (time codes are in the format hh:mm:ss):
   16:39:14
16:40:14
16:41:14
16:42:13
16:43:13
16:44:13
…
4. ?start_webrtc_archive=&archive=NameArchive&peer_id=123&archive_date=2020-08-24&archive_minute=16:40:00&archive_millis=1400
   123 – a unique ID received from the WebRTC server (see item 9 for details).
   16:40:00 – the minute you need.
   14000 – the number of milliseconds counting from the beginning of the minute.
   This request asks to begin streaming a given part of the archive starting from a specific millisecond. Note that archive_millis parameter may not exceed 60000 and needs to be reset for every minute.
5. ?stop_webrtc_archive=&archive=NameArchive&peer_id=123
   This request asks to stop streaming the given archive.
6. ?get_last_archive_time=&archive=NameArchive&peer_id=123
   This request asks for the number of the millisecond currently being played back for a given archive. This is particularly useful for synchronization (e.g. for a time line bar on the playback page). The response looks like this:
   {
"EOF":false,
"millisFromMinuteStart":15018,
"time":"16:40"
}
7. Before a page can access the archive view, it needs to load the following JS scripts:
   webrtc_view_common.js
   webrtc_adapter_min.js
8. To make the initial connection with Xeoma’s WebRTC server, the client needs to call the methods getRequestUrl and onConnect from webrtc_view_common.js. Code sample:
   $.ajax({
url: getRequestUrl("connect"),
success: onConnect,
error: function(xhr, status, error) { onError("Connect failed: " + error); }
});
9. onConnect sets the webrtcid parameter, its value should be assigned to peer_id parameter (see items 4-6). WebRTC API fetches the value itself from the STUN server, by default Xeoma uses stun.l.google.com:19302. You can change it to a different one (even your own) in the webrtc_view_common.js (line 2).
10. The resulting stream needs to be written with the <video> tag. Another method from webrtc_view_common.js (specifically, onRemoteTrack) will attach the stream to this tag. Thus, the HTML-file should have these lines:
    <video id="remote-video" autoplay></video>
<audio id="remote-audio" autoplay></audio>

September 15, 2020

Read also:
API for integration of Xeoma
HTTP Request Sender module in Xeoma