Stream live video

You can view live video from the in-cabin and the road-facing cameras. This can be done remotely from your computer, phone, or tablet while the vehicle is online. The video is streamed from the vehicle device.

Surfsight cameras stream for thirty seconds, and prompt you with the option to continue live streaming. This is hard-coded and cannot be changed.

Note

Your device must be online to view the live video.

  • If the video only streams black, it may be because the lens is covered by the lens cover accessory.
  • If the device is in standby mode, an error is returned stating that the device is offline. Wake up your device from standby to online with the POST /devices/{imei}/wakeup call.

Becoming familiar with this workflow

Currently, the Surfsight API does not have a single API specifically for live streaming. Instead, you can integrate live stream functionality by implementing a combination of our API and javascript functions.

We have built a sample application to help you become more familiar with our recommendations for implementation. Click here to download the sample application source code.

The following sections tell you more about the sample application, explain how to implement this from your platform, and show you how to use the Surfsight API to livestream video directly from remote devices as follows:

About the sample application

In the sample application provided to you, you can get up and running quickly with the existing script.js file rather than working from scratch.

The sample application includes the following files:

Name Description
hls.js Configuration file for HLS broadcast type; this streaming option may be preferable when data streaming capabilities are limited
index.html Live sample application test page
multiple_hls Stream management for HLS
multiple_webrtc Stream management for webrtc
script.js The script that runs the video streaming functionality (loading, playing, stopping)
static.js Updates parameter values to script.js
caution

Be especially careful not to change the multiplehls and multiplewebrtc files, which will prevent the application from running correctly. These files must be included in any application built to stream live video based on the Surfsight API.

Running the sample application

This process describes how to run the sample application as-is; for this, you only need to work with the static.js and index.html files.

  1. Download the sample application and copy the entire zip file to a directory on a web server.
caution

Be especially careful not to changes the multiplehls and multiplewebrtc files, which will prevent the application from running correctly. These files configure the broadcast type options.

  1. In the static.js file, modify the following parameters with your user credentials.: 'imei', 'email', and 'password'. For the purpose of this exercise, modify 'cameraType' to 1 for the road-facing camera, 2 for the in-cabin camera, and 51-54 for each successive auxiliary camera.

The following table explains these parameters in detail and provides examples of the changed parameters for illustrative purposes only:

Parameter Definition Example
imei The IMEI number of the device 357660101000198
cameraType The ID of the camera. Each camera has a camera ID. 1: road-facing camera; 2: in-cabin camera; 51-54: auxiliary cameras. 2
email The email of the user. user@email.com
password The password of the user. P@ssw0rd
  1. Browse to the path where your live view application is on the web server directory.
  2. From your application's web server, click Play Video to view the live stream. Select either webrtc or HLS streaming (two options that Surfsight offers) from the Select Video Type dropdown.

Implementing live streaming in your application

Use this process to help you integrate your platform with Surfsight for live video streaming.

  1. Download the sample application source code and copy the entire zip file to a directory on the web server where your application is hosted.
caution

Be especially careful not to change the multiple_hls and multiple_webrtc files, which will prevent the application from running correctly. These files configure the broadcast type options.

  1. Use the script.js file to help you understand the functions called in order to trigger live video streaming, stop streaming, and so on. The script.js clearly outlines the purpose of each of the different functions. Refer to this script from your application code, or alternatively, insert the functions in your application code in their relevant positions.
  2. Program your application in order to accept and insert relevant values from your users for the following parameters: 'imei', 'email', and 'password'. For example, you can build a screen including fields in which users can enter the relevant values for these paramters.

The following table explains these parameters in detail:

Parameter Definition
imei The IMEI number of the device
cameraType The ID of the camera. Each camera has a camera ID. 1: road-facing camera; 2: in-cabin camera; 51-54: auxiliary cameras.
email The email of the user.
password The password of the user.

How it works

When called by your application, if you use our sample application script.js, the following flow is triggered:

  1. document.ready function is called after page load.
  2. login function is called to login to the Surfsight system and to retrieve the user token.
  3. Following successful login, connectMedia function is called to get the media token, requesting permission for live video access. This also returns the address of the media server to which the device is connected.
  4. The camera returns the media server address to which it's connected using initVideo function call. videoSourceUrl is returned as a string.

    The complete video URL path follows this structure:

    var source = 'https://' + videoSourceUrl + '/webrtc/' + PEERID + '/' + imei + '/' + CameraType + '/' + mediaToken

    See the following table below (bottom of this section) for descriptions for each of the parts of this structure.

  5. The broadcast type is selected by a user via the video player dropdown menu.
  6. The user clicks Play Video, calling the function according to the selected broadcast type.

    Note

    In some cases the initial connection might time-out and the request will return 404 - Not Found error. Implement a retry mechanism during this step if the error is caught.

Following is a description of the different parts of the complete video URL path:

Name Description
videoSourceUrl Media server address received from connectMedia API when InitVideo function is called
webrtc Broadcast type
PEERID Session number of the webrtc broadcast provided by the media server
imei The device's unique identifier
CameraType 1 for road-facing camera, 2 for in-cabin camera
mediaToken Returned token from connectMedia API.