Introduction

This guide describes how to build a web application to play live video in the browser using the standard Eagle Eye Networks API and HTML5 web technology.

Eagle Eye Networks Video API Platform support the following video stream types:

• Main video - a high quality video stream using the h.264 video format
• Preview video - a lower quality video stream using the MJPEG video format

Both streams are available for live and recorded video for every camera.

Prerequisites

A basic knowledge of the following is necessary to follow along with this guide:

• HTML5 browser technology
• HTML5 video element
• CSS
• JavaScript
• Obtaining data from a REST API

Overview of protocols

The following table shows an overview of the supported media protocols for each stream, and for live and recorded video.

Procedure

Logging in and getting the base URL

1. In order to use the API you need to login. For more information, see Logging in
2. Use the client settings API to retrieve your Base URL that will be used for the APIs. For more information, see API URLs.

Getting /cameras

📘

Note

You can request a list of available video feeds via the API call shown below. All supported cameras can provide both the main and preview video feeds. The main video is the full h.264 high quality video stream and the preview video is a JPEG-based lower quality video steam. There are multiple URLs available to stream the actual live video for each of the feeds:

• hlsUrl - A streaming URL to play video using the HTTP Live Streaming (HLS) video protocol.
• multipartUrl - A streaming URL to transfer video using multi-part data parts as defined in RFC1341.

1. Use the following code to get cameras from the API:

Headers HTTP GET: https://<baseUrl>/api/v3.0/feeds?deviceId=123456789&include=hlsUrl,multipartUrl
Accept application/json
Authorization: Bearer <access_token>
 
Response:
{
    "nextPageToken": "",
    "prevPageToken": "",
    "results": [
        {
            "id": "123456789-main",
            "type": "main",
            "deviceId": "123456789",
            "mediaType": "video",
            "hlsUrl": "https://media.fra1p1.eagleeyenetworks.com/media/streams/main/hls/getPlaylist?esn=123456789&stream_session=11111",
            "multipartUrl": "https://media.fra1p1.eagleeyenetworks.com/media/streams/main/multipart?esn=123456789&stream_session=11111"
        },
        {
            "id": "123456789-preview",
            "type": "preview",
            "deviceId": "123456789",
            "mediaType": "video",
            "multipartUrl": "https://media.fra1p1.eagleeyenetworks.com/media/streams/preview/multipart?esn=123456789&stream_session=11111"
        }
    ]
}

Setting the Media Cookie

🚧

Important

Without setting the Media Cookie, video playback will fail with a 403 Unauthorized error when requesting any of the URLs provided by the /feeds and /media endpoints.

To access live or recorded video via the API, the browser requires a media session cookie. This is set through a two-step request process:

1. First request: A GET request is made to the /api/v3.0/media/session endpoint. This returns a 200 OK response along with a temporary session URL in the response body.

Response:

{
  "url":"https://media.c013.eagleeyenetworks.com/media/session"
}

2. Second request: A GET request is then made to the session URL. This request will return a 204 No Content response but will set a media cookie in the browser. This request will need to be sent with credentials included in order to be processed successfully. The fetch() method used in the example below does this by setting the credentials property to include.

Once the cookie is set, media URLs can be accessed directly using the <img> tag or the HTML5 <video> element.

Example Code:

<script>
    var requestOptions = {
      method: 'GET',
      headers: {
        "Authorization" : "Bearer <YOUR_ACCESS_TOKEN>"
      },
      credentials: 'include'
    };

    // First request: Get the media session URL
    fetch("<YOUR_BASE_URL>/api/v3.0/media/session", requestOptions)
      .then(response => response.json())
      .then(body => 
        // Second request: Request the session URL to set the media cookie
        fetch(body.url, requestOptions)
      )
      .then(response => console.log("Media session set, response status:", response.status))
      .catch(error => console.log('Error:', error));
</script>

After these requests, the media session cookie is stored in the browser, allowing direct playback of live and recorded video.

Playing the live preview video

1. To play live video, copy the multipartUrl for the preview video stream.

The preview video URL can be displayed in the browser via the <img> HTML tag:

<!DOCTYPE html>
<html>
    <head>
        <title>Live preview video</title> 
    </head> 
    <body>
        <img src="https://media.fra1p1.eagleeyenetworks.com/media/streams/preview/multipart?esn=123456789&stream_session=11111" />
    </body>
</html>

Playing the live main video

To play the live main video, you have two options, MultiPart Streaming and HLS (HTTP Live Streaming). Each method has certain advantages:

MultiPart Video Streaming:
This option will provide lower latency compared to HLS, making it more suitable for real-time applications such as surveillance or live interactions. Multipart streaming can also be more network-efficient in certain scenarios. Dynamic adjustments of video quality can be made based on available bandwidth, often leading to smoother streaming experiences.

HLS (HTTP Live Streaming):
HLS is widely supported across various devices and platforms, making it highly versatile for reaching a diverse audience.This method relies on standard HTTP web servers for distribution, simplifying the setup and maintenance of streaming infrastructure.

You can choose the method that best suits your requirements by using the corresponding URL:

Using the multipartUrl.

There is an SDK for NPM projects that can be used for multiPart live viewing. For more information, follow the guide for our Live Video Web SDK.

Using the hlsUrl.

🚧

Warning

Be aware that HLS live video streams have a standard delay of 6 - 8 seconds. Depending on the network, this delay can increase further. Keep this in mind when using HLS for real-time applications.

1. Select an HLS javascript player, such as HLS.js.
2. Incorporate the player into your webpage, and load the hlsUrl URL using the hls.loadSource() method.

Result: This loads the Eagle Eye Video API Platform HLS stream into your HLS player.

A third-party example player is available on https://video-dev.github.io/hls.js/demo/.

<!DOCTYPE html>
<html>
    <head>
        <script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
    </head> 
    <body>
        <video id="video" muted="muted"></video>
                
        <script>
          var video = document.getElementById('video');
          var videoSrc = 'https://media.fra1p1.eagleeyenetworks.com/media/streams/main/hls/getPlaylist?esn=123456789&stream_session=11111';
          if (Hls.isSupported()) {
          	var hls = new Hls({
              xhrSetup: xhr => {
                xhr.setRequestHeader('Authorization', 'Bearer <YOUR ACCESS_TOKEN>');
              }
            });
            hls.loadSource(videoSrc);
            hls.attachMedia(video);
          }
          else if (video.canPlayType('application/vnd.apple.mpegurl')) {
            video.src = videoSrc;
          }
        </script>        
    </body>
</html>