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

Framerate and Quality Settings

The Eagle Eye Networks Video API Platform supports different frame rates and quality settings for both the main and preview video streams. These settings can be changed via the camera settings API or through the Eagle Eye Cloud VMS.

Preview (LQ JPEG) Update-Rate Intervals

The preview video stream is a JPEG-based stream that updates at specific intervals which can be set by the end user. These settings will determine how often a new JPEG image is sent to the client. The available intervals range from 0.25 seconds to 16 seconds, allowing for flexible update rates based on the user's needs.

📘

Frame rate Equivalent

The FPS (frames per second) for the preview video stream is the inverse of the update-rate interval. For example, if the update rate is set to 0.25 seconds, it means that a new frame will be sent every 0.25 seconds, resulting in a frame rate of 4 fps.
• 0.25 s = 4 fps
• 0.5 s = 2 fps
• 1 s = 1 fps
• 2 s = .5 fps
• 4 s = .25 fps
• …and so on, where FPS is calculated as 1 / update-rate interval.

Full Video – HQ h264 - Quality settings → Frames per Second

The full video stream (main video) supports different quality settings, which directly affect the frames per second (fps) that can be achieved. The table below outlines the available quality settings and their corresponding fps for both IP cameras and analog cameras.

🚧

Warning

Always ensure that the frame-rate you request matches the camera's current quality setting. If you request frame-rate higher than the camera can accommodate, the stream will drop frames resulting in choppy playback.

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>