Stream and download device recordings

Video from trip recordings can be streamed and downloaded from the SD cards of your devices. Devices continuously record trips of more than 100 meters. They start recording once movement is detected by the built-in accelerometer. Audio is not played in these recordings.

By default, Surfsight devices come with a 128 GB SD card, which holds about 100 hours of video recordings. The oldest recorded file is cyclically replaced with a new recorded file once the SD card is full. Any of the recordings currently on the SD card can be streamed and downloaded.

The rest of this guide shows you how to use the Surfsight API to stream and download recordings, including these steps:

1. Authenticate yourself.
2. Connect media.
3. Select a recording.
4. Stream the recording.
5. Download the recording.

1. Authenticate yourself

Authenticate yourself before making any calls with the Surfsight API. For more details on authentication, see our authentication overview.

2. Connect media

Receive the authentication token and media server address to retrieve a recording or live video with the POST /devices/{imei}/connect-media request.

    curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/connect-media
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'

Returned response:

{
    "data": {
        "address": "prodmedia-us-05.surfsolutions.com",
        "mediaToken": "0e5d4dfb-56fe-4271-b9c8-86e4d7f214d5"
    }
 }

3. Select a recording

Receive a list of available recordings from every camera of your device in the desired time range with the GET /devices/{imei}/recording-ranges request.

curl --request GET https://api-prod.surfsight.net/v2/devices/{imei}/recording-ranges?start={start}&end={end}
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {token}'

Returned response:

{
    "data": [
        {
            "cameraId": 1,
            "intervals": [
                {
                    "start": "2021-10-15T15:06:35.000Z",
                    "end": "2021-10-15T15:34:38.000Z"
                },
                {
                    "start": "2021-10-16T08:19:46.000Z",
                    "end": "2021-10-16T09:13:56.000Z"
                },
                {
                    "start": "2021-10-16T10:17:32.000Z",
                    "end": "2021-10-16T12:19:52.000Z"
                }
            ]
            },
        {
            "cameraId": 2,
            "intervals": [
                {
                    "start": "2021-10-15T15:06:35.000Z",
                    "end": "2021-10-15T15:34:38.000Z"
                },
                {
                    "start": "2021-10-16T08:19:46.000Z",
                    "end": "2021-10-16T09:13:56.000Z"
                },
                {
                    "start": "2021-10-16T10:17:32.000Z",
                    "end": "2021-10-16T12:19:52.000Z"
                }
            ]
        }
    ]
}

4. Stream the recording

Enter the following URL in the source tag of the video tag in an HTML5 video player to stream the recording: https://{mediaServerAddress}/rec/{imei}/{cameraId}/{mediaToken}/{startTime}/{videoDuration}/{qualityLevel}/rec.mp4

When creating the URL to stream the recordings, use the following strings that were aquired from the steps above:

5. Download the recording

Enter the following URL into a web browser or create a hyperlink with it to download the recording file: https://{mediaServerAddress}/download/{imei}/{mediaToken}/{imei}_{cameraId}_{startTime}_{videoDuration}_{qualityLevel}.mp4

When creating the URL to download the recordings, use the strings that were aquired from the steps above.